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TOPIC  A,1  - MT/T  MOUITOl 


A,  SODUXE  MfiE 

Hulti -Terminal  Tasking  Honitor 
Program-ID  - RHITSOP 
Hodnle-IC  - MTTSUP 

B,  AMXYST 

SoBert  X,  "Rutledge 
Neoterics,  Inc. 

C,  MODTJXE  FUNCTION 

The  MT/T  Konxtor  is  the  single  program  which  effects 
communication  among  the  NASIS  application  program,  the 
TSS/360  cperating  system  and  the  NASIS  user 

community.  This  program  is  responsible  for  the 
allocation  of  the  NASIS  resources  to  the  user 

community,  the  handling  of  all  terminal  input/output 
for  the  user  community  and  the  processing  of  those 
NASIS  functions  which  require  more  or  less  direct 
interface  with  TSS/360,  In  addition,  the  Monitor 
supports  processors  for  those  NASIS  user  commands  which 
pertain  to  the  Monitor  itself  (such  as  communicating 
with  other  users,  listing  active  users  and  so  on) 

The  MT/T  Monitor  is  written  completely  in  360/67 
machine  code  via  the  TSS/360  Assembler.  The  TSS  user 
macro  library  (SYSMAC)  and  the  TSS  system  programmer 
macro  library  (ASMHAC)  are  used  to  obtain  the  TSS 
system  facility  macros  (for  terminal  communication, 
data  management  and-  so  on)  and  some  macros  in  the 
Monitor  itself  are  used  for  convenience  in  coding, 
(These  particular  macros  are  described  below.) 

Although  the  primary  consideration  in  the  coding  of  the 
Monitor  is  execution  time,  special  effort  has  been  made 
to  make  the  coding  itself  as  lucid  and  informative  to 
the  reader  as  possible.  Profuse  self-documentation  -and 
comments  make  it  quite  probable  that  specific  questions 
left  unanswered  by  this  document  may  be  answered  by  a 
quick  look  at  the  listing  of  the  Monitor. 

Finally,  all  the  facilities  of  the  Monitor  have  been 
incorporated  into  one  program.  This  is  done  merely  to 
get  everything  in  the  same  place  for  convenience;  it 
is  felt  that,  nothing  would  be  really  gained  by 
splitting  the  Monitor  into  several  programs. 


D. 


BATA  SEQUIBEMENTS 
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Not  Applicable 

PROCESSING  REQPIEEaENTS 

1,  Top  le-vel  Flovchart 
Not  Applicable 

2,  Narrative 

a*  Ecnitor  Kacros 

The  raacros  incorporated  into  the  Monitor 
itself  (they  are  the  first  things  in  the 
program)  are  used  only  for  ease  of  coding  and 
reading.  They  are  in  no  way  necessary  in  the 
sense  that  they  could  be  replaced  by  the 
expanded  coding  with  no  detremental  effect  to 
the  execution  of  the  Monitor. 

Each  macro  included  in  the  Monitor  is  now 
described  • along  with  the  parameters  it 
expects  and  its  precise  function. 

■1.  PHT 

This  macro  is  used  to  convert  an 
internal  hexadecimal  data  item  into  a 
corresponding  EBCDIC  data  item  (i.e., 
convert  internal  hex  into  printable 
characters) . It  is  used  mostly  for 
formatting  error  codes  and  so  on  for 
the  operator.  The  operands  for  this 
macro  are  the  target  field  address  and 
length  and  the  source  field  address  and 
length. 

2.  STRK 

The  BTRN  macro  is  used  to  cause  control 
to  be  returned  to  a point  described  by  a 
TSS/360  interrupt  push-down  area.  This 
macro  merely  points  a register  at  the 
push-down  area  (the  only  operand)  and 
issued  the  svc  which  causes  control  to 
be  transferred  to  the  MTTRTRN  routine  to 
switch  push-down  areas.  (Por  a further 
discussion  of  this  technique,  see  the 
description  of  the  MTTRTRN  routine.) 

3.  MSG 

This  macro  is  the  means  the  Monitor  uses 
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to  send  messages  to  the  <NASIS). 
operator.  The  operands  for  this  macro 
are  the  message,  message  and 
(optionally)  a return  address.  This 
address  is  branched  to  after  the  message 
is  sent  if  it  is  specified  to  the  macro. 
This  macro  sets-up  the  message  pointer 
In  register  one,  the  message  length  .in 
register  zero  and  the  return  address  (if 
any)  in  register  fourteen  and  calls  the 
HTTPEHPT  routine,  (In  addition,  if 
operator  response  is  expected,  this 
macro  negates  register  zero.)  See  the 
MTTPBMPT  routine  description  for  further 
information. 

TIHE 

This  macro  is  a more  useful  version  of 
the  (TSS)  EBCBTIHE  macro.  It  accepts 
the  same  operands  as  EBCDTIHE  but  also 
accepts  defaulted  operands  and 
register-notation  operands.  This  macro 
sets-up  parameter  registers  and  calls 
the  HTTTIHE  routine  so  as  to  conserve 
space  in  the  PSECT,  For  more 
information,  see  the  description  of  the 
HTTTiaE  routine. 

HOVE 

This  is  the  macro  which  every  program 
written  having  to  move  data  around  has 
in  it  in  some  form  or  another.  Ours 
puts  the  operands  for  the  macro  (target 
field  pointer,  source  field  length  and 
source  field  pointer)  in  registers  and 
calls  the  MTTHOVE  routine,  the 
description  of  which  later  in  this 
document  will  give  you  more 
information. 

THAN 

This  macro  is  analogous  to  the  HOVE 
macro  except  that  it  translates  instead 
of  moving.  The  operands  for  this  macro 
are  the  field  pointer,  the  field  length 
and  the  address  of  the  translation 
table.  After  setting-up  the  parameters 
this  macro  calls  the  HTTTEAN  routine  to 
actually  translate  the  text. 
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7 . .A  ENTE 

/T 

This  important  macro  is  nsed  to  take 
care  of  all  the  linkage  conventions, 
setting-np  hase  registers,  terminating 
timers  and  so  on  each  time  the 
application  calls  one  of  the  Honi tor’s 
service  routines.  Basically,  it  saves 
all  the  calling  registers  (including  the 
floating-point  registers) , the  return 
address  and  the  program  mask  in  the 
push-down  area  in  the  task  control  table 
(see  the  description  of  the  TCTE  table 
below) , kills  the  user’s  time-slice 
timer  by  calling  MTTONTIM  and  sets-np 
all  the  base  registers  for  the  Honitor. 
There  are  no  operands  for  this  macro 
which  is  kind  of  the  mirror  image  of  the 
EETN  macro  discussed  next. 

8.  BETS 

This  macro  is  used  to  cause  return -to 
the  caller  of  a Honitor  service 
routine.  It  expects  the  registers  and 
so  on  to  have  been  saved  by  a 

corresponding  EHTH  macro  and  effects 
return  by  merely  flagging  the  sub-task 
as  dispatchable  and  branching  to  the 
gueue-scanning  routine  (HTTFNDQI) . (By 
and  by  the  queue-scanner  will  find  this 
sub-task  waiting  for  dispatch  and  issue 
a BTBB  macro  pointing  to  the  push-down 
area  in  the  user’s  task  control  table.)  - 

9.  BECOBD 


This  macro  is  nsed  to  record  an  event 
and/or  data  within  the  Monitor.  It  uses 
a 7HH00K-like  mechanism  to  cause  the 
System  Internal  Performance  Evaluation 
(SI PE)  processors  to  record  a data  area 
onto  the  system’s  recording  tape. 
There  are  various  and  sundry  operands  to 
this  macro  which  describe  the  animal 
being  recorded.  You  are  referred  to  the 
section  on  event  recording  (below)  for 
details  on  this  and  the  rest  of  the  data 
recording  mechanism  within  the 
Honitor. 


b 


Overview 
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^flie  HT/T  Monitor,  with  the  exception  of  the 
code  to  set-up  NASIS  and  to  take  it  back 
down,  consists  of  one  main  routine  to  scan 
the  work-to-do  queues  which  the  program  uses 
to  keep  track  of  what’s  going  on  and  a bunch 
of  subroutines  to  actually  do  the  indicated 
work,  Thus,  the  flow  of  control  through  the 
Monitor  is  queue-scanner  to  subroutine  to 
handle  a requested  function  to  queue-scanner 
and  so  on,  When  the  queue-scanning  routine 
finds  nothing  whatsoever  to  be  done.  It 
enters  the  (TSS)  «»waiT-«  condition. 

Js  most  of  the  Monitor  consists  of  the 
subroutines  to  perforin  specific  functions  for 
the  Monitor,  a quick  list  of  these  functions 
is  in  order.  Eirst,  there  are  the  task 

controlling  functions:  dispatching  and 

time-slice-ending  a sub-task.  There  are 
several  routines  for  performing  input/output 
on  a sub-task  terminal.  There  are  quite  a 
few  routines  to  handle  NASIS  ’’user"  commands 
•which  are  more  easily  processed  by  the 
Monitor  than  by  any  other  part  of  NASIS,  And 
there  are  the  normal  subroutines  which  can  be 
called  by  anybody  for  the  ■ grunge  tasks: 
moving  text,  translating  text,  sending 
messages  and  so  on. 

One  final  section  of  the  Monitor  doesn’t 
quite  fit  the  description  above.  This  is  the 
asynchronous  (SYSIN)  attention  interrupt 
processing  routine.  This  is  the  program 
which  gains  ccntrol  when  the  (HT/T)  operator 
hits  the  ATTN  key  on  the  operator’s  terminal. 
Thus,  this  is  the  routine  which  actually 
communicates  with  the  operator.  All  it  does 
is  read  (Monitor)  commands  from  him  and 
exente  them, 

External  Specifications 

1,  Module  Name  - RMTTSUP 

2,  F3ECT  Name  - MTTSDPP 

3,  CSECT  Name  - HTTSUPC 

q.  Entry  Point  Names 

a.  NASIS  (To  initialize  and  set-up 
for  execution  the  entire  NASIS 
system. 
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b.  HTURBITE  (To  «rite  text  to  a 

sob-tasK  terminal.) 

c.  HTTBIAB  (To  read  text  from  a 

sub-task  terminal.) 

d.  MTTE8EAD  (To  first  write  text  to 
and  then  read  text  from  a sub-task 
terminal.) 

e.  HTTELDSH  (To  empty  the  output  text 
buffer  by  writing  it  to  a sub-task 
terminal.). 

f.  HTTXTE  (To  obtain  various 
information  about  a sub-task. ) ■ 

g.  MTTPASS  (To  prompt  a sub-task:  user 

for  his  "security  code”.) 

h.  HTTGETIH  (To  obtain  the  elapsed 

time  statistics  for  a sub-task, ) 

i.  MTTHUST  (To  enter  "must-complete” 

mode  for  a sub-task.) 

HTTTSE  (To  force  a time-slice-end 

condition  on  a sub-task.) 

k.  HTTLHT  (To  obtain  the  current 

NASIS  limits  for  printing » 

searching  and  so  on.) 

l.  HTTPGHIS  (To  process  a program 

interruption.) 

m.  HTTSPEAK  (To  process  an  operator 

asynchronous  attention 

interruption.) 

n.  MTTTSEHD  (To  process  a 

time-slice-end  timer 

interruption.) 

o.  MTTBTRN  (To  process  a "return"  SVC 

interruption, ) 

p.  ETTBESET  (To  process  the  operator 


g* 

attention 
command, ) 
KTTKA 

resetting 

(To  process  the  user 

(TSS) 

”KA" 

r* 

command.) 

HTTKB 

(To  process  the 

! user 

"KB” 

Sa 

command, ) 
HTTMSG 

(To  process  the 

user 

"HSG” 

t.  , 

command.) 

HTTHEIP 

(To  process 

the 

user 

u. 

"HELP”  command.) 
HTTUSEBS  (To  process 

the 

user 

"USEES"  command.) 
BTTBUSEB  (TO  process 

the 

user 

"NUSEBS" 

HTTDATIH 

command* ) 

(To  process 

the 

user 

"DATETIHE 

HTTWAIT 

” command.) 
(To  process 

the 

user 

"BAIT"  command.) 

y,  HTTDTAB  (Pointer  to  the  BT/T  Oser 
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Information  Table  for  the  executing 
snb-task  (if  any)  . ) • 

■z»  MTTTCT  (Pointer  to  the  start  of 
the  terminal  table.) 

aa«  HTTTRQ  (Pointer  to  the  executing 
terminal  table  entry  (if  any),) 
bb»  HTTTCTE  (Pointer  to  the  executing 
task  control  table  (if  any).) 

5.  External  References 

a.  SYSINDCB  (Pointer  to  the  data 

control  block  for  SYSIN.), 

b.  TSATIR  (Pointer  to  the  BASIS 

attention  interrupt  handling 

routine.) 

Datasets 

The  Monitor  requires  two  datasets  which  are 
used  in  ifs  initialization  phase.  One 
contains  the  list  of  BASISIDs  which  are 
allowed  on  the  system  and  the  other  contains 
Monitor  commands  which  are  to  be  executed 
automatically  before  BASIS  is  opened  up  to 
the  user  community. 

1.  BASIS. DSERIDS 

This  dataset  is  the  one  containing  the 
list  of  allowable  BASISIDs,  It  also 
contains  information  about  which  BASISID 
is  allowed  to  look  at  which  file,  but 
the  Monitor  only  uses  the  first  four 
fields  in  each  record:  the  BASISID,  the 

password  (if  any),  the  time-slice  value 
to  be  initially  assigned  to  the  BASISID 
and  the  authority  code  to  be  initially 
assigned  to  the  BASISID.  - (This  last 
field  is  not  used  at  the  present.) 

2.  BASIS. COHMABDS(O) 

This  TSS/360  ”line”  dataset  contains  any 
■Monitor  commands  which  the  operators 
wishes  to  have  automatically  executed 
each  time  BASIS  is  brought  up.  Examples 
of  such  commands  are  ’’limit”,  ’’pgmstop”, 
"news",  and  so  on. 

COBTEOI  TABLES 

The  following  section  discusses  the  tables 
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wiicli  the  Monitor  nses  to  drive  itself.  Only 
general  descriptions  are  given  here  for  the 
formats  of  the  tables;  we  would  rather  yon 
Icnow  what  their  functions  are.  Each  of  these 
tables  is  described  by  a DSECT  in  the  listing 
of  the  Monitor,  so  you  are  referred  there  for 
the  formats  of  these  tables, 

1,  Terminal  Table  (TRQ)  (DSECT  "TEQDSECT") 

This  is  the  most  basic  table  used  by  the 
Monitor.  It  is  a list  and  count  of  the 
users  attached  to  NASIS  at  any 
particular  time,  TSS,  through  the  ’*Q” 
macros  (EBITEQ  and  EEADQ)  return  a 
terminal  identifier  entitled  the 
"relative  terminal  number”, . This  is  a 
number  from  zero  to  the  current  number 
of  attached  users  and  this  is  the  number 
which  is  used  to  index  the  terminal 
table  to  find  the  entry  for  a particular 
user.  All  the  pointers  to  information 
tables  for  the  user  originate  in  the 
terminal  table.  The  things  contained  in 
this  table  are:  the  pointer  to  the  task 
control  table,  the  pointer  to  any 
message  control  blocks  for  this 
sub-task,  the  symbolic  device  address  of 
the  terminal,  the  NASISID  of  the  user 
attached  to  this  terminal  (if  any,  this 
field  is  filled  in  during  logon),  the 
flag  indicating  whether  the  sub-task  is 
waiting  for  dispatch  and  the  ”WAIT” 
timer  for  the  sub-task,  if  any, 

2,  Task  Control  Table  (TCT) 

(DSECT  "TCTDSECT”) 

This  is  the  table  that  contains  all  the 
information  abont  and  working  storage 
for  a sub-task.  All  the  (normal) 
register  saveareas,  task-related 
temporaries,  task  indicators.  Monitor 
saveareas,  timing  information,  I/O 
buffer  information  and  so  on  are  in  this 
table.  In  addition,  all  the  user 
information  is  here;  NASISID,  password, 
task-id  and  so  on.  When  the  Monitor  can 
locate  this  table  for  a particular  user, 
it  knows  all  there  is  to  know  • about 
him. 
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Message  Control  Block  (HCB) 
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(DSECT  «HCBDSECT«) 

This  control  block  is  constructefl  each 
tiiB€  a message  is  to  be  sent  to  a 
sub-task«  All  it  contains  are  the 
message  text  and  length  and  a pointer  to 
the  next  message  control  * block  on  the 
chain,  if  there  is  one* 

Attention  Table  (ATN) 

(DSECT  "ATNBSECT") 

This  table  is  dynamically  built  each 
time  a user  hits  the  ATTEUTION  (or 
BREAK)  key  at  his  terminal.  The  table 
contains  all  the  information  about  the 
interrupt  (uhich  is  almost  asynchronous) 
to  pass  on  to  the  KASIS  • attention 
processing  routine.  In  addition,  it 
contains  a savearea  for  that  routine  to 
temporarily  save  the  contents  of  the 
interrupted  DSA.  In  addition,  if  the 
attention  interruption  processor  wishes 
to  modify  the  address  to  which  • control 
is  to  be  returned  after  the  interrupt  is 
•processed,  it  so  notifies  the  Honitor 
through  this  table* 

ElKBQ  Return  List  (DSECT  «CHAERQ») 

This  is  a control  block  constructed  and 
maintained  by  TSS.  It  is  the 
information  returned  to  the  Monitor 
after  it  executed  a READQ  or  SEITEQ  and 
contains  the  terminal  number  mentioned 
earlier  plus  information  about  any  text 
read  in  and  some  indicators  for  line 
hang  and  attention. 

User  Table  Entry  (DSECT  "USRDSECT")  • 

This  thing  is  really  only  a descriptor 
for  the  format  of  a record  in  the 
HASISIDs  list  dataset, 

«NASIS* USERIDS". 

Parameter  list  (DSECT  "PRIDSECT") 

This  is  the  control  table  passed  to  the 
Hcnitor  whenever  the  application  calls 
it  to  process  a terminal  I/O  request. 
It  describes  the  parameter  list  expected 
from  and  returned  to  the  caller.  (This 
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parameter  list  is  identical  to  . the  one 
used  by  TSS/360  GATE  except  that  there 
is  no  ADCON  pointing  • to  control 
information  in  the  first  word.) 

8.  Operator  Attention  Savearea 
(DSECT  ”SAVDSECT«) 

This  table  is  bnilt  by  the  Monitor  each 
time  the  operator  hits  ATTBUTION  and 
caases  entry  to  the  operator  attention 
interrupt  processor  (MTTSPEAK) • This 
table  contains  all  the  registers  and 
ypsw  as  of  the  interrupt  and  is  kept  (in 
a chain)  because  the  operator  is  allowed 
to  hit  ATTENTION  again  while  in  this 
routine  and  we  wish  to  be  recursive. 
Thus,  this  table  contains  only  the 
registers  and  VPSN  as  of  the  interrupt 
and  a pointer  to  the  next  table  on  the 
chain,  if  any. 

9,  limit  Table  {DSECT  "IIHDSECT") 

This  table  is  where  the  Monitor  keeps 
all  its  information  about  HASIS  limits. 
(The  things  which  may  be  limited  are 
total  number  of  users,  number  of  users 
of  a particular  class,  number  of  records 
in  a set  which  may  be  searched  on  or 
printed  and  so  forth.)  This  table 
consists  of  a header  containing  the 
limiting  numbers  for  those  things  which 
are  always  limited  and  entries  for  each 
class  of  NASISID  which  has  been  manually 
limited  by  the  operator.  . 

JO.  Eeccrding  Area  (DSECT  «EECDSECT") 

This  table  is  the  area  in  which  the 
Monitor  posts  the  data  which  it  records 
(via  the  TSS  ”SIPE”  mechanism,  see  the 
section  on  recording  below) • This  table 
is  also  used  to  pass  the  data  along  to 
the  recording  mechanism  in  the  TSS 
Supervisor.  It  consists  of  the  actual 
data  to  be  recorded  plus  some  control 
and  save  areas  which  the  recording 
mechanism  expects. 

11.  Data  Control  Block  (DCB  ) 

(DSECT  «CHADCB'») 
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This  table  is  used  by  the  Monitor  to 
interface  with  the  TSS  access  methods 
used  in  the  handling  of  the  various 
datasets  the  Monitor  uses  (see  the 
section  on  datasets  above) • One  DCS  is 
set-up  by  the  Monitor  and  serves  for  all 
the  datasets  it  uses.  Eor  more 
information  on  the  Data  Control  Bloch, 
you  are  referred  to  the  "System  Control 
Blocks"  Program  logic  Manual 
(GY28-2011). 

12.  Interrupt  Storage  area  (ISA) 

(BSECT  CHAISa) 

This  control  table  is  really  page  zero 
in  virtual  memory.-  The  DSECT  supplied 
by  TSS  is  used  to  direct  the  Monitor-  to 
the  correct  memory  locations 
corresponding  to  the  items  it  wishes  to 
reference.  (For  further  information  on 
the  Interrupt  Storage  Area,  you  are 
referred  to' the  "System  Control  Blocks" 
Program  Logic  Manual  (6128-2011)  . 

retailed  Description 

The  following  section  contains  a detailed 
description  of  the  MT/T  Monitor.  It  is 
assumed  that  the  reader  has  a firm  grasp  of 
360/67  machine  language  and  the  principles  of 
the  TSS/360  Operating  System, 

1.  MTTSTABT  routine 

HTTSTABT  (with  the  entry  point  NASIS)  is 
the  routine  which  the  MT/T  Interface 
Module  (C2CTC)  calls  when  the  HT/T 
operator  enters  the  MTT  command  at  the 
operator  terminal.  On  entry,  this 
routine  establishes  linkage  and  sets-up 
all  the  program  base  registers  (El 3 for 
the  PSICT,  E8^B12  for  the  CSECT)  , It 
next  initializes  some  of  the  more 
important  program  variables— the  flags, 
user  counter,  table  pointers  etc.  It 
then  initializes  the,  (Monitor’s) 
recording  mechanism  and  obtains  a 
two-page  pool  to  build  the  limit  table, 
news  text  area  and  terminal  table  in. 
The  termi-nal  table  is  aligned  on  a page 
boundary  so  as  to  minimize  paging  later 
on.  Coincident  with  building  these 
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tables,  their  pointers  are  posted  in  the 
PSECT.  next,  the  (operator)  attention 
is  specified  and  enabled,  as  is  the 
program  interrupt  routine  and  the  SVC  63 
interrupt  routine  {for  the  BETUBN  SVC) • 
In  all  cases,  the  SIB  function  is  used 
to  actually  specify  the  interrupt 
routine.  At  this  point,  the 
liASISID-containing  dataset 
(KASIS.USEBIDS)  is  read  and  the  four 
■fields  mentioned  earlier  from  each 
record  are  posted  in  an  in-core  table 
{this  is  done  so  that  the  Monitor 
doesn’t  have  to  waste  time  reading  the 
dataset  each  time  a user  logs  on) • 
After  this  dataset  is  processed,  the 
command  dataset  (BASIS, commands  (0) ) is 
read  in  and  the  commands  in  it  are 
executed.  This  is  the  last  function  for 
this  routine,,  and  after  it  is  completed, 
it  sends  a message  to  the  operator  (MSG) 
to  the  effect  that  it  is  finished  and 
commences  execution  of  NASIS  by  exitting 
to  the  HTTEINDQ  routine  at  MTTENDQ1. 

KTTIND  Boutine 

This  routine  is  the  inverse  of  the 
HTTSTABT  routine  and  is  entered  by  being 
the  target  of  the  STIMEE  issued  in  the 
shutdown  routine  (HTTSHUT) . (It  may 
also  be  entered  by  a direct  branch  to 
BTTEBD1  in  the  case  of  an  immediate 
shutdown  request.)  Upon  entry  in  either 
case  it  first  scans  through  the  terminal 
fable  looking  for  active  users  and 
calling  the  MTTQUIT  routine  to  log  them 
'Off  after  sending  them  messages  telling 
-them  that  the  system  is  shutting  down. 
After  it  has  gotten  rid  of  all  the  users 
in  this  fashion,  it  returns  the  storage 
for  the  userid  table  and  deletes  all  the 
interrupt  routines  via  the  TSS  DIE 
function.  After  this  is  done,  the 
routine  sets  a timer  such  that  it  sits 
idle  for  fifteen  seconds.  This  is  done 
so  that  all  the  user  terminals  have  time 
to  finish  typing  their  EBEEQ  messages 
before  the  Monitor  returns  control  to 
the  TSS  system  which  will  terminate  any 
I/G  going  on  each  terminal  is  it  gets  a 
chance.  After  the  wait  is  over,  the 
routine  frees  the  pool  of  memory  used  to 
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b^iiia  the  three  tables  mentioned  earlier 
and  returns  to  the  system  through 
standard  return  linkage. 

MITFINBQ  Eoutine 

This  is  the  routine  which  scans  through 
the  various  queues  looking  for  work  for 
the  Honitor  to  do.  It  has  two  entries^ 
EITFINDQ  for  callers  who  wish  control 
returned  to  them  at  the  termination  of 
the  I/O  operation  for  the  sub-task  and 
BTTTHD01  for  callers  who  • are  merely 
finished  with  a task.  The  only 
difference  is  that  at  HTTFIEDQ,  the 
registers  are  saved  in  the  TCT  for  the 
sub-task  in  question  and  at  HTTFNDQI 
they  are  not.  The  first  thing  either 
routine  does  is  to  zero  out  the  pointers 
for  the  current  TCT  and  TBQ  so  as  not  to 
confuse  any  of  the  interrupt  routines. 
It  then  sets-up  the  pointers  and  indices 
to  the  terminal  table  in  registers  (for 
speed,  it  may  have  to  scan  the  terminal 
table  several  times) . The  first  scan 
through  the  terminal  table  is  to  look 
for  sub-tasks  with  outstanding  messages. 
If  any  are  found,  they  are  send  via 
calls  to  the  HTTBRITE  routine  at 
MTTWPIT1,  (Ail  internal  calls  ‘ on 
HTTWlilTE  are  made  to  HTTHBITI.)  Before 
a message  is  sent,  however,  the  MCB  for 
the  sub-task  is  locked  out  so  that  we 
don’t  try  to  send  two  messages  to  the 
task  at  the  same  time  (this  would 
confuse  the  Q routines  which  ■ don’t 
quite  know  what  to  do  with  a busy 
condition  from,  a terminal)  . Also,  no 
messages  are  sent  to  terminals  with  the 
”1/0  active”  flag  on  in  the  TCT  for  the 
same  reason.  After  the  terminal  table 
has  been  scanned  for  messages,  it  is 
scanned  for  sub-tasks  waiting  to  be 
forced,  For  each  that  is  found,  a 
message  is  sent  and  the  HTTQUTT  routine 
is  called  to  actually  disconnect  the 
terminal.  Care  is  taken  so  that  this- 
routine  doesn’t  try  to  force  a task  more 
than  once.  These  two  scans  are  not 
particularly  functionally  important,  bat 
they  must  be  done  first  because  if  they 
are  done  after  the  I/O  and  execute 
scans,  the  terminals  would  always  appear 
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to  be  busy  and  both  these  functions  rely 
on  the  terminal  being  free. 

The  next  scan  is  done  with  the  aid  of 
the  TSS  PIUDQ  function.  This  facility 
scans  through  the  terminals  attached  to 
BASIS  and  returns  a non-zero  return  code 
if  there  are  any  with  I/O  completion 
status.  If  the  Honitor  finds  one  such, 
it  records  the  return  code  (IBC)  and 
then  chechs  for  a hung-up  phone  line  (a 
flag  in  the  FIHDQ  list)  and  performs  a 
logical  disconnect  on  the  terminal 
(HTTQUIT)  if  it  finds  this  to  be • the 
case.  It  also  manually  checks  for  an 
indication  of  attention  in  addition  to 
whatever  code  it  has  and  calls  the 
HTTCIEAE  routine  to  ’'flush  out”  all 
other  outstanding  attentions  from  the 
terminal  {because  ETAH  has  the  nasty 
habit  of  telling  us  that  there  were  1-3 
attentions  when  there  was  in  fact  only 
one) • After  these  checks  are  made  (if 
it  was  a line  hang,  control  has  gone 
somewhere  else)  the  routine  locates  the 
TCT  for  the  terminal  with  the  completion 
status  by  indexing  into  the  terminal 
tabls  with  the  relative  terminal  number 
and  locating  the  TCT  pointer  in  the 
terminal  table  entry.  It  then  posts  the 
terminal  in  question  as  the  currently 
running  task,  restores  the  registers 
which  it  must  have  saved  in  the  TCT 
(because  everybody  calls  MTTFIHDQ  to 
await  the  completion  of  all  I/O 
operations)  and  returns  to  the  original 
caller  through  register  14,.. 

If  no  terminal  completion  stati  were 
found,  the  final  scan  through  the 
terminal  table  is  made.  This  scan  looks 
for  sub-tasks  waiting  to  be  dispatched. 
These  will  have  the  work-to-be-done  flag 
on  in  the  THQ  entry.  After  one  of  these 
is  found,  quick  checks  for  terminal  busy 
{it’s  receiving  a message)  and  system 
down  {somebody  did  a shutdown)  are 
made.  If  the  terminal  is  busy,  the  task 
is  merely  skipped  over;  if  the  system  is 
shutting  down,  the  task  is  marked  as  not 
waiting  for  dispatch  and  the  scan  is 
continued.  If  the  sub-task  is  found  to 
be  OK  to  be  dispatched,  the  pointers  are 


PSGE  18 


set  to  reflect  the  task  no^j  . executing 
and  that  task  is  returned  to  by  a direct 
branch  to  the  dispatching  routine 
(HTiDISPR) . 

If  absolutely  no  work  is  found  to  be 
done,  the  Monitor  relinguishes  execution 
by  teliing  TSS  it  must  wait  for  some 
event  to  complete  related  to  the  NASIS 
task.  This  is  done  by  merely  issuing  a 
(TSS)  WAIT  macro.  Upon  return  from  the 
control  is  transferred  to  the 
beginning  of  the  queue-scanner  to 
determine  what  event  it  was  which 
completed, 

HTTEISPE  routine 

This  is  the  routine  which  transferrs 
control  to  a sub-task  using  the  saved 
registers  and  vpsw  in  the  task  control 
table.  all  it  does  is  start  the  user’s 
time-slice  timer  by  calling  the  HTTTIHEE 
routine  and  then  execute  an  BTRU 
pointing  to  the  push-down  area  in-  the 
TC5. 

MTTTIHEE  routine 

This  routine  handles  the  initiation  of 
the  STIHEB  which  starts  a sub-task’s 
time-slice  execution  time  timer.  Upon 
entry,  it  saves  a few  working  registers 
in  the  TCT  for  the  sub- task,  picks-up 
the  value  to  be  used  for  the  time-slice 
this  time  (TCTNTS) , adds  one  to  it 
(figuring  that  the  coding  in  the  Monitor 
plus  the  SVC  processing  tine  for  the 
BETDBM  will  add  up  to  a millisecond)  and 
issues  the  STIHEB  using  timer  number 
seven.  If  the  STIHEB  fails,  the  task  is 
forced  since  we  can’t  run  without 
time- slicing.  Bet urn  from  this  routine 
is  to  the  caller  through  register  14. 

BTTDHTIH  routine 

The  KTIOBTIH  routine  is  called  when  a 
Monitor  service  routine  has  been  entered 
and  there  is  still  a time-slice  timer 
running.  It  turns  off  that  timer  as  the 
Bonitor  does  not  want  to  be  time-sliced 
while  it  is  handling  a service  reguest 
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for  -the  applcation.  Upon  entry,  some 
registers  are  saved  in  the  TCT  for  the 
±ask  and  a TTIMEE  (CANCEt  option)  is 
issued  to  turn  off  the  timer  and  return 
the  amount  of  unused  time  in  it*  This 
unused  time  subtracted  from  the  amount 
of  time  the  last  time  slice  started  with 
is  added  to  the  user’s  total  CPO  time 
used  (after  the  same  one  millisecond 
added  in  HTTTIHEB  is  subtracted  off) . 
Also,  a check  is  made  here  for  a recent 
call  on  HTTHUST  (flag  TCTMOST) . If  this 
has  happened,  the  next-time- slice  value 
is  reset  to  the  user’s  time  slice  value 
(as  it  was  originally  set  to  an  hour  by 
MTTHDST).  An  error  from  the  TTIHEE  does 
not  kill  the  task,  but  the  operator- Is 
notified  of  the  anamoly,  Peturn  is, 
again,  through  register  14  to  the 
caller. 

BTTTSElSD  routine 

HTTTSENP  is  the  entry  point  specified  as 
the  exit  routine  to  be  called  when  the 
time-slice  timer  runs  out.  Thus,  it  is 
the  routine  which  is  called  to  recognize 
the  fact  that  a time  slice  is  finished 
and  cleans-up  and  updated  the  timing 
statistics  and  places  the 
time-slice-ended  user  back  in  the 
dispatch  gueue.  After  it  is  entered,  it 
loads  all  the  base  registers  including 
the  bases  for  the  terminal  table  entry 
and  TCT  for  the  executing  task.  It  then 
checks  to  see  if  the  timer  interrupt 
occured  in  the  Monitor  and  if  it  did  it 
ignores  the  interrupt  by  merely  there 
was  indeed  a user  executing  at  the  time 
of  the  interrupt  by  seeing  of  the  TCT 
pointer  is  zero.  If  it  is,  a branch  is 
taken  to  the  code  to  ignore  the 
interrupt  (below) . 

At  this  point,  MTTTSENl)  updates  the 
user's  timing  statistics  by  adding  the 
value  used  to  initiate  the  last 
time-slice  (TCTNTS)  into  the  accumulated 
CPU  time  for  the  task  (TCTCPTJTH) . 
TCTNTS  is  also  reset  to  the  user’s 
time-slice  value  (TCTTIMER) . 

Now  the  routine  checks  to  see  if  the 
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interrupt  occured  while  the  Monitor  was 
executing  by  checking  the  interrupt  VPSH 
address  against  the  lower  and  upper 
fcounfls  of  the  Monitor.  If  the 
interrupt  occured  within  the  Monitor,  it 
is  ignored  by  undoing  the  linkage  and 
returning  to  the  Task  Monitor  hy 
branching  through  register  14.  If  the 
interrupt  was  legitimate,  all  the 
registers  and  VPSB  as  of  the  interrupt 
are  saved  by  moving  the  push-down  area 
provided  by  the  Task  Monitor  into  the 
user’s  TCT.  The  routine  then  places  the' 
task  in  the  dispatch  queue  by  turning  on 
that  flag  in  his  terminal  table  entry 
(TCTWKSTJ)  . It  now  overlays  the 
registers  and  VPSH  in  the  push-down  area 
with  the  registers  for  the  Monitor  and 
address  of  MTTFKIiQI  and  causes  control 
to  return  to  the  queue-scanner  by 
returning  to  the  Task  Monitor,  (This 
means  of  transferring  control  is  used 
'throughout  the  Monitor  because  the  Task 
Monitor  will  get  confused  if  we  don’t 
return  to  it  after  each  interrupt  so  it 
can  dequeue  them  from  its  interrupt 
chains.) 

MTTTASKI  routine 

The  MTTTASKI  routine  is  the  routine 
which  is  branched  to  directly  when  the 
queue  scanner  finds  an  ’’initial 
connection”  interrupt  as  a return  from- a 
PINEQ  operation.  It  means  that  a user 
has  "just  typed  BEGIN  NASIS  at  a 
terminal.  After  some  initialization, 
this  routine  checks  to  see  if  the 
application  is  shutting  down  (DOHHSN  on)- 
and  if  this  is  the  case,  it  pretends  the 
terminal  hung  up  and  calls  HTTQDIT  to 
disconnect  it.  At  this  point,  the 
number  of  active  users  (HTTTJSER#)  is 
incremented  by  one. 

MTTTASKI  now  checks  to  see  if  the 
terminal  is  one  of  the  CRTs  recognized 
by  the  application— a 2260  or  CCI  CC-30. 
If  it  is,  the  size  of  the  area  for  the 
TCT  is  increased  as  these  devices 
require  a larger  i/o  buffer  for  their 
screens,  (CC-30 s are  located  by 
examining  the  list  of  CC-30  Symbolic 
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Device  Addresses  hard-coded  into  the 
Honitor;  2260s  are  located  by  checking 
the  deyice-type  field  in  the  FINDQ 
return  list.)  Now  that  it  knows  how 
much  space  it  needs,  this  routine 
obtains  space  for  the  task  control  table 
via  GBTMAIN,  As  in  all  cases  within 
this  routine,  failure  to  obtain  space 
for  one  of  the  tables  results  in  the 
terminal  being  disconnected  via  the 
HTTQOIT  routine.  After  the  table  is 
gotten,  its  pointer  is  posted  in  the 
terminal  table  entry  for  this  sub- task 
and  as  many  fields  are  filled  in  in  the 
fCT  as  the  Honitor  can,  for  example  all 
the  buffer  pointers  and  counters, 
terminal  type,  and  so  on.  The  sign-on 
time  for  the  user  is  obtained  via  the 
BELTIM  macro  <this  is  the  number  of 
micreseconds  since  March  1,  1900)  and 
posted  in  the  TCT, 

As  this  point,  the  limit  table  is 
investigated  to  see  if  this  user  is 
allowed  on,  the  criterion  being  the 
number  of  (total)  users  allowed  on  and 
the  number  that  are  already  on.  If  this 
user  overflows  the  limit,  he  is  so 
notified  and  kicked  off  by  calling 
MTTQDIT,  If  he  is  allowed  on  {so  far) 
his  NASISID  and  password  are  prompted 
for  and  read  by  calls  on  the  HTTBEAD  and 
MTT-WIIITE  routines  (at  HTTNBITI  and 
HTTBIADI,  respectively).  After  the 
user’s  NASISID  is  obtained,  the  limit  on 
the  members  of  his  class  (which  is  the 
first  two  characters  of  the  NASISID)  are 
checked  and  he  is  kicked  off  as  before 
if  the  limit  for  his  class  has  been 
reached.  Also,  only  three  tries  to 
enter  a correct  NASISID  or  password  are 
allowed.  After  all  the  information 
about  the  user  is  gathered  in,  his 
terminal  table  entry  and  TCT  are  filled 
in  the  rest  of  the  way.  At  this  point, 
a message  is  sent  to  the  operator 
telling  him  (her)  that  somebody  is 
logging  on. 

Now  that  the  user  is  properly  connected, 
he  is  informed  of  several  things.  If  a 
shutdown  has  been  requested,  the  user  is 
informed  of  the  time  at  which  the 
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application  will  terminate.  He  is  also 
sent  any  news  that  has  been  typed  in 
(this  is  taken  from  the  HEHSLTH  and 
NElS!TEXa:  fields).  Einally,  a call  to 
MTTFinsH  at  HTTF1SH1  is  made  to  empty 
all  this  information  plus  his  Monitor 
logon  message  to  his  terminal.  Now  the 
user  is  given  virgin  registers  and  a 
■ypSE  pointing  to  the  application  entry 
point  (these  are  posted  in  his  TCT)  and 
he  is  placed  in  the  dispatch  gueue. 
This  routine  exits  to  the  gueue  scanner 
at  HTTFNDQ1. 

HTIQHIT  routine 

This  is  the  logoff  processor  for  the 
application.  It  also  is  used  to  force 
users  off  the  system  for  one  of  a number 
of  reasons.  There  are  two  entries  to 
this  routine;  HTTQHIT  for  callers  who 
don’t  wish  to  be  returned  to  and 
HTTQDIT1  for  those  who  do.  This  routine 
first  gets  itself  a safe  place  to  save 
registers  and  then  decrements  the  count 
of  active  users  by  one  (to  match  the 
early  processing  of  this  counter  by  the 
HTTTASKI  routine)  and  flags  the  user  as 
being  ditched  by  posting  the  TCTQUIT 
flag  in  his  TCT  (if  he  has  a TCT, 
remember  he  could  have  done  something 
like  hong  up  his  terminal  during  the 
logon  process) . After  cleaning- op  the 
user,  killing  off  any  queue  switches, 
turning  off  his  time-slice  timer,  and  so 
*on,  a message  indicating  the  logoff  is 
sent  to  the  operator. 

How  all  MCBs  and  attention  tables  left 
un-released  are  gotten  rid  of  by 
FEEEHAIHing  them,  (This  is  done  because 
it  is  quite  likely  that  attention  tables 
in  particular  were  not  released  during 
the  user's  session  because  some 
attention  processing  is  of  the  GOTO  form 
instead  of  the  BETUEN  form,)  Now  the 
total  elapsed  CPU  and  connect  times  are 
calculated  and  formatted  into  a logoff 
message  for  the  user.  The  user's  TCT  is 
now  freed  {after  the  terminal  number  is 
saved  from  it)  and  his  terminal  table 
entry  is  xeroed  out.  The  logoff  message 
is  transmitted  to  the  user's  terminal  as 
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ao  option  on  the  FEEEQ  macro  which  is 
nsed  to  disconnect  his  terminal*  This 
is  -the  last  operation  this  rontine  has 
to  perform  and  when  it  is  finished,  it 
either  returns  to  the  caller  through 
register  14  or  to  httpndqi  {gueue 
scanner)  depending  on  which  entry  was 
originally  called. 

HTTIiSlTE  routine 

This  is  the  routine  which  is  used  to 
write  text  to  a sub-task  terminal.  It 
has  two  entry  points!  HTTWBITE  for 
calls  from  the  application  program  (it 
assumes  standard  TSS/360  type  I linkage 
and  performs  initialization  with  the 
ENTB  macro)  and  HTTHPITI  for  calls  from 
within  the  monitor  itself  (it  assumes 
register  14  to  contain  the  return 
address  and  all  the  other  base  registers 
to  be  already  set-up) . For  external 
callers,  the  parameters  to  the  routine 
(text  pointer  and  length)  are  taken 
from  the  parameter  list  pointed  to  by 
register  1 and  for  internal  callers  they 
are  moved  from  registers  0 and  -1.  This 
is  all  the  initialization  that  HTTHEITE 
does. 

Checks  are  now  made  for  one  of  the 
accepted  ClTs  and  if  one  is  found, 
control  is  transferred  to  one  of  the  two 
routines  to  process  these  terminals. 
They  are  described  below.  At  this 
point,  all  the  registers  used  throughout 
the  routine  are  set-up.  They  include 
registers  containig  constants,  input 
string  and  output  buffer  pointers  and 
counters  and  zeroed-out  registers  for 
character  moving.  The  first  thing 
checked  for  is  a * j • at  the  end  of  the 
input  string  signifying  that  the  caller 
wishes  to  inhibit  the  carriage-return 
that  is  normally  added  to  the  end  of 
each  line  of  output,  A flag  is  turned 
on  to  remember  about  this  later  if  the 
character  is  found.  In  addition,  the 
colon  is  removed  from  the  text.  All 
trailing  blanks  are  also  stripped  from 
the  end  of  the  text  to  be  output  (for 
neatness) , A final  check  is  made  to  see 
if  the  task’s  I/O  buffer  is  completely 
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filled  and  if  it  is,  it  is  emptied  out 
by  calling  HTTP1SH1  to  send  the  buffer 
to  the  user's  terminal. 

If  the  last  operation  completed  at  the 
terminal  was  a read,  idles  are  added  to 
the  front  of  the  text  to  give  the 

carriage  time  to  complete  returning  to 
the  left  margin.  Also  in  this  case,  a 
linefeed  is  added  to  the  front  of  text 

going  to  teletypes  (as  then  do  not 

automatically  add  a linefeed  to  their 
’•new  line”  seguence) . If  the  last 
operation  to  the  terminal  was  a write 
and  the  terminal  is  a teletype  and  the 
last-written  line  was  not 

carriage-hanged,  a linefeed  is  added  to 
the  front  of  the  text  for  the  same 

reason.  At  this  point,  the  caller's 
fext  is  processed. 

All  processing  of  the  caller's  output 

text  is  done  character  by  character.  A 

character  is  fetched,  examined,  possibly 
given  special  treatment  and  then  placed 
in  the  I/O  buffer  in  the  sub-task's  TCT. 
Special  treatment  is  given  to  the 
following  text  characters; 

a.  Idle  characters  are  ignored 
completely  (because  they  are  used 
for  special  applications  in  the 
Monitor. 

b.  Linefeed  characters  are  followed  by 
idle  characters  for  some 
terminals. 

c.  Backspace  characters  cause  the 
distance  across  the  carriage  (for 
calculating  the  number  of  idles 
required  after  a carriage-return) 
to  be  decremented  by  two, 

d.  Carriage-return  characters  are 
followed  by  enough  idles  to  allow 
the  carriage  to  return  to  the  left 
margin.  Also,  the  distance  across 
the  paper  is  zeroed, 

e.  Tab  characters  are  followed  by  an 
estimated  number  of  idles  (we  don’t 
know  how  far  the  tab  is  going  to 
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move  the  carriage)  ..  The  distance 
across  the  paper  is  also  given  an 
estimated  increment. 

If  at  any  time  during  the  moving  of  text 
the  I/O  buffer  is  filled,  it  is  flushed 
to  the  terminal  by  a call  to  the 
HTTPIUSH  routine  at  HTTPLSH1. 

after  all  the  text  has  been  processed,  a 
carriage  return  is  added  to  the  end  of 
the  line  if  the  caller  did  not  request 
the  carriage  to  be  hanged.  Idles  are 
added  after  this  carriage  return  to 
allow  the  carriage  to  return  to  the  left 
margin.  If  the  TCT  I/O  buffer  has  been 
exactly  filled  by  this  write,  it  is 
flushed  out  by  calling  HTTFISHI,  after 
all  this  is  done,  all  the  buffer 
pointers  and  counters  and  distances  are 
updated  in  the  TCT  and  flags  indicating 
whether  the  line  was  hanged  or  not  and 
that  the  last  operation  was  a write  are 
posted  in  the  TCT,  The  method  of  return 
to  the  caller  is  determined  by  the  entry 
point  called. 

The  two  special  routines  for  writing  to 
CRTs  merely  move  the  text  to  the  TCT  I/O 
buffer,  call  the  HTTWEQ  routine  to  write 
it  cut,  call  MTTFINRQ  to  wait  for  the 
write  to  complete  and  branch  to  the 
common  exitting  code  for  HTTRBITR, 

1-1,  WTTCHhRS  subroutine 

This  subroutine  is  used  to  insert 
characters  into  the  TCT  I/O  buffer.  It 
is  used  extensively  by  the  RTTWRITE 
routine  to  move  idles,  linefeeds  and  so 
on.  It  determines  whether  there  is  room 
for  the  characters  it  has  been  requested 
to  post  in  the  buffer  and  if  there  is  it 
merely  moves  them  in.  If  there  is  not 
room,  it  flushes  the  buffer  to  the 
user's  terminal  by  calling  HTTFLSH1  and 
then  moves  the  characters  into  the 
buffer,  Beturn  is  to  the  caller 
through  register  14, 

12,  HTTHEAR  routine 

This  is  the  routine  which  reads  text 
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froTB  a sub-task  terminal*  It  too  has 
±Mo  entry  points,  one  for  the 
application  to  call  and  one  for  the 
Monitor  to  call.  MTTEEAD,  the  external 
entry,  does  its  linkage/base  register 
initialization  via  the  EMTB  macro. 
MTTBEaDI,  the  Monitor’s  entry,  merely 
moves  the  parameters  to  the  appropriate 
registers.  The  parameters  in  the  case 
of  a call  to  MTTBEAD  are  in  a standard 
TSS  parameter  list.  This  routine  first 
sees  whether  there  is  any  output  text  in 
the  TCT  I/O  buffer.  If  there  is,  it  is 
written  to  the  terminal  and  then  text  is 
read  from  the  terminal  by  a call  to  the 
MTTSSQSB  routine.  If  there  is  no  text 
in  the  buffer,  the  terminal  is  merely 
read  by  a call  to  the  MTTBDQ  routine. 
If  there  are  no  error  returns  from  the 
"Q"  routine,  the  HTTFINbQ  routine  is 
called  to  await  completion  of  the  I/O 
operation. 

After  the  text  has  been  read  from  the 
terminal  and  presented  to  the  MTTBEAD 
routine  by  pointers  in  the  FINDQ  return 
list,  it  is  translated  from  line  code  to 
EBCDIC  with  the  TRAN  macro.  If  the  user 
is  in  ’’folded”  (KB)  mode,  the  text  is 
"translated  once  more  to  "fold”  his  lower 
case  input  to  upper  case.  If  there  is  a 
carriage  return  on  the  end  of  the  input 
string,  it  is  stripped  off, . If  the  line 
if  input  ends  with  either  a or  a 

”/”,  the  user  has  cancelled  the  line  and 
control  returns  to  the  common  entry  to 
read  another  line  from  the  terminal. 
Otherwise,  the  line  is  scanned  for 
backspace  characters  which  are  processed 
by  moving  the  text  to  the  right  of  the 
backspace  character  two  spaces  left 
(over  the  backspace  and  the  character 
preceeding  it) « Under  no  circumstances 
if  the  line  backspaced  over  the  "left 
margin”.  After  the  backspaces  are 
processed,  a check  is  made  to  determine 
whether  or  not  the  line  ends  with  a 
indicating  continuation.  If  it  does, 
the  continuation  flag  is  turned  on  in 
the  return  codes  being  built  and  the 
section  for  processing  trailing  blanks 
is  skipped  over.  If  there  is  no 
continuation  indicator,  all  trailing 
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blanks 
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at  the 

end  of 
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line 
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text 

input 

is 
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the  length  reguested 

hy 

the  caller.  If 

the  user 

typed 

in  more 

-text  than  the  caller  allowed  for,  the 
truncation  indicator  is  tamed  on  in 
the  return  code  ieing  built  and  only  the 
amount  of  text  requested  by  the  caller 
is  moved.  Otherwise  all  the  text  the. 
user  typed  is  moved  to  the  caller’s 
target  area.  Now  the  terminal  buffers 
and  controls  are  released  back  to  the 
system  via  the  CLEAEQ  facility  and  the 
returns  from  the  CLEAEQ  are  checked  for 
attention.  If  an  attention  is  detected 
during  the  CLEAEQ,  the  attention 
indicator  is  posted  in  the  return  codes 
being  built. 

At  this  point,  all  the  flags  indicating 
what  has  happened  are  posted  in  the  ICT, 
the  length  of  the  user’s  input  text  is 
posted  in  the  caller’s  parameter  list 
and  the  caller  is  returned  to  either  by 
a branch  through  register  14  for 
internal  callers  or  a RETN  macro  for 
external  callers. 

13.  aiTNEEAD  routine 

This  routine  is  mostly  a convenience 
item  for  the  application.  All  it  does 
is  internally  call  HTTHfilTE  and  then 
HTTEEAB  (at  HTTHEITI  and  MTTREABI)  to 
effect  a ”GTWAS"-type  function.  There 
is  no  internal  entry  to  this  routine. 
After  the  routine  has  performed 
initialization  with  the  ENTE  macro  it 
moves  the  parameters  from  the  TSS 
parameter  list  to  the  registers  the 
internal  entries  to  HTTNBITE  and  MTTEEAD 
expect  and  calls  each  of  the  routines. 
Checks  for  errors  from  mttwbite  are  made 
before  the  call  to  MTTREAD  is  made  and 
if  any  are  found,  the  call  to  NTTEEAD  is 
skipped  and  the  error  indicators  are 
returned  to  the  caller.  Return  to  the 
caller  from  this  routine  is  made  via  the 
EETN  macro. 

14.  HTTFLDSH  routine 
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This  routine  is  the  routine  which 
empties  the  I/O  buffer  (in  the  TCT)  to 
the  user’s  terminal  and  resets  all  the 
buffer  pointers  in  the  TCT  to  reflect 
the  now-erapty  buffer.  It  has  an  entry 
for  external  callers  (HTTPLOSB)  which 
initializes  with  the  EBTB  macro,  and  an 
entry  for  internal  callers  (HTTFLSH1) 
which  merely  saves  some  working 
registers. 

after  initializaion  if  finished,  this 
routine  checks  to  see  if  there  is 
anything  at  all  in  the  buffer.  If  there 
isn't,  it  merely  branches  to  the  code  to 
return  to  the  caller.  If  there  is,  the 
routine  checks  to  see  if  the  terminal 
type  is  a 1050.  If  it  is,  an 
end-of-block  character  is  added  to  the 
end  of  the  text  in  the  buffer.  (This 
routine  relies  on  there  being  an  extra 
character  in  the  buffer  at  the  end  of 
same  in  case  the  buffer  is  filled.)  In 
the  case  of  an  external  caller,  the 
MTTWBQ  routine  is  called  to  empty  the 
buffer;  in  the  case  of  an  internal 
caller,  the  ’’Q"  routine  is  one  of  the 
parameters  to  this  routine  and  that  is 
the  routine  which  is  called.  After 
return  from  the  "Q”  routine,  the 
HTTTINDQ  routine  is  called  to  await  the 
completion  of  the  I/O"  operation.  After 
this  is  finished,  the  caller  is  returned 
to  either  by  branching  through  register 
14  or  by  a RETS  macro. 

MTTBDQ,  STTRRQ  and  aTTWBQAR  routines 

These  three  routines  are  the  routines 
which  perform  the  actual  I/O' reguests  on 
user  terminals.  After  performing  the 
initialization  unique  to  each  operation 
and  issuing  the  I/O  request,  they  all 
user  common  coding  to  analyse  the 
results  and  return  (label  QGOHHOH). 

HTTIDQ  saves  some  working  registers  and 
then  issues  a SEADQ  reguest  to  the 
appropriate  relative  terminal  number 
with  the  operand  TSBSL=N  (because  we  do 
cur  own  translating) . It  then  ■joins  the 
common  finalization  code. 
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HTTIEQ  saves  registers  and  translates 
the  text  to  be  uritten  to  line  code  by 
nsing  the  THAN  macro,  (In  the  case  of  a 
2260,  no  translation  is  done  as  of  yet,). 
It  then  issues  a IRITEQ  request  pointing 
to  the  appropriate  relative  terminal 
number,  output  text  and  output  text 
length  with  the  additional  operand 
TBliSOOT=E  (since  we  just  translated  the 
text  ourselves) • It  then  joins  the 
common  finalization  code, 

HII'REQAE  behaves  almost  the  same  as 
HTIRBQ  except  that  the  operands  RESP=Y 
and  TRHSIR-R  are  added  to  the  WEITEQ 
request.  It  then  falls  through  to  the 
common  finalization  code. 

After  the  operation  has  been 
requested,  QCOMHOR  executes  into  a 
branch  table  indexing  on  the  return  code 
from  the  operation.  This  table  either 
adjusts  the  return  code  to  the  Honitor*s 
internal  code  set,  branches  to  an  error 
routine  which  tells  the  operator  about 
the  unexpected  ”Q”  return  code  and  then 
pretends  it  was  an  I/O  error,  or  leaves 
a zero  (good)  return  code  alone.  It 
then  restores  all  the  working  registers 
(except  the  one  with  the  return  code) 
and  returns  to  the  caller  through 
register  14, 

HTTATTR  routine 

MTTATTK  is  the  routine  which  is  branched 
to  directly  by  the  queue-scanner  when 
that  routine  finds  a ”naked’>  attention 
return  code  from  one  of  the  terminals 
after  a FIKDQ  operation.  This  means 
that  we  have  received  almost  an 
asychrounous  interrupt  from  the  sub-task 
and  it  requires  some  special  processing, 
(It  is  almost  an  asychronous  interrupt 
because  we  are  assured  that  it  can  only 
be  found  at  the  end  of  a time-slice,  so 
we  really  have  available  the  ’’interrupt” 
registers  and  -vpsw,)  • Also,  the 
application  has  set-up  routines  • which 
are  to  he  called  when  attention 
interrupts  (this’  kind,  not  the  kind 
which  merely  add  a bit  to  the  I/O 
request  return  code)  occur  and  the 
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routine  itself  requires  special 
l>rccessiTig« 

On  entry,  HTTA'ITN  locates  the  TCT  for 
the  terminal  which  got  the  interrupt  by 
Indexing  into  the  terminal  table  on  the 
relative  terminal  number  in  the  EINDQ 
list.  If  there  is  no  TCT,  the  terminal 
is  hung-up  by  the  issuance  of  a FEEEQ 
operation  with  no  operands.  After  the 
ICT  is  found,  it  is  marhed  not  busy  and 
the  terminal  table  entry  and  TCT  pointer 
are  posted  as  being  the  currently 
executing  ones.  At  this  point,  the 
HTTCLEAE  routine  is  called  to  ’'flush 
out"  any  more  attention  indicators  from 
the  terminal. 

Now,  the  routine  has  to  check  a bunch  of 
special  cases.  If  any  of  the  following 
events  are  happening,  the  attention  will 
he  ignored: 

a.  The  application  is  shutting  itself 
down  (HTTEND  has  been  entered) , 

b.  The  user  is  not  completely  logged 
on  {TCTONSN  is  *zero)  , 

c.  The  user  is  being  logged  ' off 
(ICTQUIT  has  been  entered  for 
him)  , 

d.  The  user  is  waiting  to  be  forced 
(TCTFOBC  is  on). 

Also,  if  this  routine  can  determine  that 
there  is  a set  of  saved  registers  for 
the  HTTFINDQ  routine,  it  "cheats”  and. 
merely  signals  to  the  caller  of  MTTFIHDQ 
that  it  got  an  attention  return  code 
from  whatever  I/O  operation  was  going 
on.  This  is  done  because  it  is  simpler 
than  calling  the  application  attention 
routine  and  accomplished  the  same 
thing. 

If  control  gets  this  far,  the  attention 
is  deemed  valid  and  the  application 
attention  processing  routine  has  to  be 
called,  HTTATTN  first  obtains  an  area 
in  which  it  can  post  all  the  information 
about  the  interrupt  to  be  sent  along  to 
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-the  attention  routine.  If  there  is  no 
space  for  this  attention  table,  the 
operator  is  notified  and  the  attention 
is  ignored.  Otherwise,  this  new 
attention  table  is  added  to  the  end  of 
the  chain  of  attention  tables  for  this 
sub-'tash  (the  chain  starts  at  label 
fCTAITN  in  the  TCT) . After  the  table  is 
linked  in,  all  the  interrupt  information 
(push-down  area)  is  moved  from  the  IC*T 
to  the  attention  table.  Now  all  the 
registers  necessary  for  the 
application’s  attention  routine  are 
set-up  in  the  ICT  (in  the  interrupt 
register/vpsw  slots)  .■  After  this  is 
finished,  the  dispatch  flag  is  turned  on 
in  the  terminal  table  entry  and  the 
queue-scanner  is  exit ted  to  so  the  task 
will  be  dispatched  in  turn  later,  (When 
it  is  dispatched,  it  will  be  dispatched 
to  the  application  attention  routine.) 

Upon  return  from  the  attention 
processing  return  (it  is  not  necessarily 
going  to  come  back  to  us,  remember) , the 
registers  from  the  attention  table  are 
moved  back  to  the  TCT,  the  attention 
table  is  un-chained  from  the  attention 
table  chain,  the  task’s  dispatch  flag 
is  turned  on  again  and  the  control  is 
returned  to  the  queue-scanner  at 
tiTTEHDQl,,  (Ihis  will  cause  the  sub-task 
to  either  take  up  where  it  was 
interrupted  or  to  take  up  where  the 
application  attention  routine  wants  it 
to  go,  having  modified  the  interrupt 
registers  and  VPSW  in  the  attention 
table.) 

BTICIEAB  routine 

MTTCIEAE  is  a fudge  which  is  necessary 
because  the  TSS  supervisor  terminal 
routine  (ClATC)  tends  to  tell  us  lies 
about  the  number  of  times  a user  hits 
his  attention  key.  This  routine  merely 
issues  EINDQs  to  the  terminal  in 
question  until  it  quits  returning  stati. 
It  indexes  into  a branch  table  with  each 
return  code  from  the  EIHDQ  until  either 
the  status  becomes  zero  or  an  error 
occurs,  in  which  case  it  calls  the 
routine  in  the  queue- scanner  to  hang  up 
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the  terminal*  After  a zero  states  is 
found,  the  caller  is  returned  to  by 
branching  through  register  14* 

18.  BTTGETIM  routine 

This  routine  is  called  by  the 
application  when  it  wishes  to  obtain  the 
elapsed  CPD  and  connect  times  used  by  a 
sub-tash  thus  far.  After  initializing 
the  linkage  by  an  ENTH  macro  it . issues  a 
EEPTIH  macro  to  obtain  the  current 
system  tirae~stamp  and  subtracts  the 
sign-on  time  from  the  result.  (This  is 
done  in  64-bit  fixed-point  arithmetic.) 
The  other  result  sent  back  by  this 
routine  is  merely  the  TCTCPTJTS  field 
■ which  already  contains  the  sub-task’s 
elapsed  CPU  time.  Beturn  is  made  via 
the  EETU  macro. 

19,  STTXTE  routine 

This  routine  is  called  by  the 
application  to  obtain  the  following 
information  about  a particular 
sub-task; 

a.  The  NASISID  of  the  user, 

b.  The  password  (if  any)  for  the 
user, 

c.  The  taskid  of  the  sub-task, 

d.  The  indicator  for  whether  the 

application  is  running  in  HT/T  mode 
or  in  standalone  mode, 

e.  The  indicator  for  whether  the  user 

is  conversational  or 

non-con versational* 

f.  The  indicator  for  whether  or  not 

usage  statistics  is  to  be 
disabled. 

After  this  routine  performs  its 
initialization  with  the  ENTE  macro  it 
starts  looking  at  the  parameter  list 
sent  to  it  by  the  caller.  It  only  fills 
in  the  positional  output  fields  as  long 
as  there  are  available  target  spots  in 
the  parameter  list.  The  first  output  is 


PAGE  33 


the  NASISID  which  is  put  into  a string 
dope  sector  (SDV)  pointed  to  the 
first  parameter.  The  password  in  put 
into  the  SEV  pointed  to  by  the  second 
parameter.  The  taskid  is  a 32-bit  fixed 
number  which  is  pointed  to  by  the  third 
parameter,  (Note:  This  output  used  to 
be  a character  string  also, ) The  next 
two  parameters,  the  flags,  are  always 
set  "on”  (one)  and  are  put  into 
bit-string  dope  vectors  as  pointed  to  by 
the  last  two  parameters.  The  last  flag 
(usage  statistics  disabled)  is  first 
turned  off  then  the  internal  flag  for 
this  condition  is  checked  and  if  it  is 
son,  the  parameter  flag  is  turned  on. 
After  it  is  all  finished,  this  routine 
•returns  to  the  caller  by  using  the  EETN 
macro, 

20.  BTTHOST  routine 

HTTKDST  is  the  routine  which  the 
application  can  call  when  it  wishes  to 
perform  a function  without  being 
time-sliced.  All  it  does  is  initialise 
with  ENTB  and  then  overlay  the 
next-time-slice  value  in  the  TCT 
(ICTNTS)  with  a value  of  one  hour  and 
turn  on  the  indicator  which  .says  MTTHUST 
has  been  called  so  that  the  HTTUNTIM  can 
make  the  appropriate  corrections  the 
next  time  it  is  called.  The  caller  is 
returned  to  with  the  EETN  macro, 

21,  MTTPiSS  routine 

This  routine  is  called  to  prompt  the 
user  for  his  "security  code”.  This 
routine  is  used  instead  of  in-line  code 
because  it  already  has  the  mechanism  in 
it  to  prompt  for  a parameter  with 
”black-out",  (It  uses  this  mechanism  to 
prompt  the  user  for  his  password  at 
logon  time,)  After  this  routine  is 
entered,  it  performs  linkage  and 
base-register  initialization  with  the 
ENTS  macro.  Calls  to  HTTNEIT1  and 
HTTEEAD1  are  used  to  actually  perform 
the  prompting  I/O  at  the  user’s  terminal 
and  this  routine  does  not  check  the 
entered  string.  It  merely  sends 
whatever  it  gets  back  to  the  caller. 
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Eettirn  is  made  with  a EEIDN  macro. 

22.  MTTTSE  routiiie 

This  routine  is  used  by  the  application 
program  to  force  a time-slice-end  on  a 
sub-tasJc  (for  example,  to  get  out  of 

"must-complete”  mode).  All  it  does  is 

EWTE,  EEC  and  then  RSTN  which  has  the 

effect  of  taking  the  user  out  of 

execution  mode,  setting  him  up  to  be 
dispatched  again  later  and  calling  the 
queue-scanner  to  see  if  there  is 
anything  to  be  done  before 
re-dispatching  this  user. 

’2-3.  WTTIHT  routine 

This  routine  is  called  by  the 
application  to  obtain  the  current  limits 
on  the  NASIS  resources  (prints, 

searches,  sorts  and  records) • After 
initializing' with  the  ENTE  macro,  this 
routine  merely  moves  those  four  "words 
from  the  limit  table  header  (label 
IIHPENTS  in  LIMDSECT)  to  the  16-byte 
field  pointed  to  by  the  caller’s 
parameter  list.  Return  to  the  caller  is 
made  via  the  SETN  macro. 


2ft.  BTTSPEAK  routine 

HTTSPEAK  is  the  entry  point  specified  in 
the  interrupt  control  block  which 
handles  attention  interrupts  from  the 
SYSIH  terminal  (operator’s  terminal), 
When  it  is  called,  it  conforms  to  the 
linkage  laws  and  sets-up  all  the  base 
registers  for  the  Honitor.  In  addition, 
if  there  was  an  e'xecuting  sub-task,  its 
time-slice  timer  is  turned  off.  This 
routine  then  obtains  an  area  to  save  all 
the  interrupt  registers  and  VPSfl  in  and 
chains  this  area  to  a chain  of  similar 
saveareas.  This  is  done  because  the 
operator  is  allowed  to  hit  attention 
while  a previous  attention  is  being 
serviced.  After  the  table  is  chained  in 
and  the  interrupt  information  moved  into 
it,  the  Task  Honitor  is  returned  to 
briefly  so  it  can  dequeue  the  interrupt 
from  its  own  chains.  At  this  point,  the 
operator  is  permitted  to  hit  attention 
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again — before  this  time,  the  attention 
Hill  be  ignored  by  TSS* 

after  all  its  initialization  is  done, 
HTISPEAK  prompts  the  operator  to  enter  a 
Monitor  command  by  typing  a guestion 
marl?  at  his  terminal  and  nnlocking-  the 
keyboard.  If  the  response  from  the 
operator  is  just  a carriage  return,  he 
is  leaving  "debug”  mode  and  a branch  is 
made  to  the  code  to  return  to  the  point 
of  interruption.  If  text  was  typed  in, 
MTTSCaw  is  called  to  parse  it  into  a 
command  name  and  operands.  Errors  from 
that  routine  cause  a message  to  be  sent 
to  the  operator  and  a branch  taken  to 
the  exitting  code.  otherwise,  the 
OPEECOM  (operator  command)  ■ table  is 
searched  for  a match  with  the  command 
entered  by  the  operator.  If  a match  is 
found,  the  appropriate  command 
processing  routine  pointer  is  picked  out 
of  the  table  and  the  routine  is  called. 
If  no  match  was  found,  a check  is  made 
to  see  if  the  Monitor  is  in  "debug" 
mode.  If  it  is,  the  line  entered  by  the 
operator  is  fed  to  an  OBEY  macrc  in  case 
it  is  a TSS  command.  If  the  Monitor  is 
not  in  "debug"  mode,  an  error  message  is 
sent  to  the  operator  and — the  exitting 
code  is  branched  to. 

After  a command  has  been  accepted  one 
way  or  another  and  control  returns  from 
either  the  command  processor  or  the  OBEY 
macro,  another  check  is  made  to  see  if 
the  Monitor  is  in  "debug"  mode.  If  it 
is,  the  operator  is  prompted  again  (he 
will  be  prompted  until  he  enters  a null 
line) — if  it  isn’t,  the  exitting  code  is 
fallen  through  to. 

At  exitting  time,  the  attention  routine 
is  deleted  and  re~specified  (Cl ATT,  DIB, 
SIB,  DSATT)  so  that  TSS  doesn’t  lose  it. 
After  this  is  done,  all  task  interrupts 
are  disables  by  turning  on  a flag  in  the 
ISA  and  the  interrupt  information  is 
moved  from  the  current  sawearea  to  the 
Monitor’s  PSECT,  The  savearea  is  now 
un-chained  and  returned  to  the  system 
(FEEEMAIN) , any  su6-task  time-slice 
timer  is  restarted,  task  interrupts  are 
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re-enables  and  the  routine  returns  to 
the  point  of  interruption  by  executing  a 
ElBH  macro  pointing  to  the  interrupt 
push-down  area  which  it  moved  into  the 
'Monitor’s  PSECT. 

25.  HTTPCaiH  routine 

This  is  the  entry  point-  specified  in  the 
interrupt  control  block  for  program 
interruptions.  On  entry,  it  saves  the 
interrupt  registers  and  VPSW  in  the 
Monitor’s  PSECT  and  causes  the  Task 
Honitor  to  degueue  the  interrupt  from 
its  lists  by  returning  to  it  and  telling 
it  to  return  to  the  Honitor  instead  of 
the  point  of  interruption.  If  a 
sub-task  was  executing,  his  time-slice 
timer  is  turned  off.  In  addition,  if  a 
user  was  running,  his  dispatch  flag  is 
zeroed,  just  in  case  somebody  decides  to 
dispatch  him  later. 

Kow  . this  routine  composes  an  operator 
message  containing  the  program  interrupt 
yPSE  and  all  the  interrupted  general 
registers.  After  this  message  is 
composed  and  formatted,  it  is  sent  to 
the  operator  via  the  HSG  macro.  After 
the  message  is  sent,  the — PGHSl  switch 
is  interrogated  to  determine  whether  to 
pause  so  that  the  operator  can  ’’look 
around”.  If  that  switch  is  on,  a CLIC 
macro  is  issued,  causing  control  to 
return  to  TSS  command  language  until  the 
operator  enters  a ”G0”  command. 

Upon  return  from  the  CLIC  or  if  no  CLIC 
was  issued,  the  routine  checks  to  see  if 
a user  was  responsible  for  the 
interrupt.  If  no  user  was  running,  exit 
is  made  directly  to  MTTPHDQ'1.  If  a user 
was  responsible,  he  is  sent  a message 
via  HTTS5IT1  telling  what  happened  to 
him  and  then  he  is  forced  off  with  a 
call  to  HTTQUIT. 

26.  HTTSCAH  subroutine 

This  subroutine  is  called  by  sections  of 
the  Monitor  that  wish  to  parse  a string 
containing  a Honitor  command.  It  merely 
separates  the  line  into  elements 
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delimited  by  commas  or  (strings  of) 
blanks  and  posts  pointers  and  counters 
for  each  so-delimited  operand  into  a 
table  called  PABAHS,  In  addition,  it 
recognizes  the  guote-marlc  convention 
used  by  TSS  itself  to  allon  the  nse  of 
commas,  blanks  or  quote  marks  inside  of 
operands.  If  it  finds  an  unmatched 
quote  mark  somewhere  in  the  string,  it 
sets  the  condition  code  to  non-zero 
before  returning,  otherwise  the 
condition  code  is  set  to  zero.  Be turn 
in  either  case  is  through  register  14. 

27.  HITKA  routine 

This  routine  is  the  routine  which  the 
application  calls  to  process  a user  ”KA” 
command.  After  initializing  the  entry 
(ENTE)  it  merely  turns  on  the  TCTKA  flag 
in  the  user’s  TCT  and  returns  via  the 
EETN  macro. 

28.  HTTKB  routine 

This  routine  is  the  processor  for  the 
user  ”KB"  command  and  turns  the  TCTKA 
flag  off  instead  of  on.  The  same 
linkage  is  used  as  for  MTTKA. 

29.  HTTHSG  routine 

This  is  the  routine  which  is  used  to 
send  a message  from  one  user  to  another 
(where  on.e  of  the  users  in  question  is 
allowed  to  be  the  HT/T  operator).  Entry 
at  HTTHSG  is  for  the  application  to  use 
when  it  finds  a user  "HSG”  command  and 
entry  at  HTTHSG  1 is  used  by  the  Honitor 
to  process  an  operator  **HSG”  command. 

At  HTTHSG,  initialization  is 
accomplished  by  the  ENTE  macro.  The 
userid  of  the  message  recipient  is  then 
verified  by  a call  to  the  HTTGTUSB 
subroutine.  A check  is  then  made  to  see 
if  there  is  any  text  to  be  sent.  If 
there  is,  the  HTTHAMG  subroutine  is 
called  to  place  the  message  on  the 
receiving  user’s  HCB  queue  or  to  send 
the  message  immediately  to  the  operator 
(whose  userid  is  OPEBATOB) . Eeturn  to 
the  application  is  made  by  the  BETH 
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macro* 

St  HTTHSG1,  the  parameters  (from  PAEftHS) 
are  picked-ap  and  the  userid  is  checked 
by  a call  to  MTTGTDSE.  The  text  length 
is  also  checked  and  if  there  is  some 
text  to  be  sent,  it  is  attached  to  the 
appropriate  user’s  HCB  chain  by  a call 
to  the  HTTRASG  subroutine.  Beturn  from 
this  routine  is  via  register  14, 

30,  HTTHSUG  subroutine 

This  is  the  subroutine  which  actually 
causes  a message  to  get  sent  to  either  a 
user  or  the  MT/T  operator.  In  the  case 
of  a user,  it  obtains  space  for  an  HCB, 
puts  the  message  into  it  and  hangs  the 
HCB  to  the  end  of  the  chain  of  HCBs 
pointed  to  by  a word  in  the  terminal 
table  entry  (TBQHSGPT)  and  turns  on  the 
■flag  in  the  terminal  table  entry 
indicating  that  there  is  at  least  one 
message  in  that  gueue. 

In  the  case  of  a message  intended  for 
the  MT/T  operator  (userid  OPEEfiTOR) , the 
message  text  is  moved  to  a (Monitor) 
message  area  (after  a time-stamp  field) 
and  the  whole  thing  is  sent  immediately 
to  the  operator  via  the  MSG  macro, 

Eeturn  from  either  section  of  this 
subroutine  is  through  register  14, . 

31,  MTTHEIP  routine 

KTTHEIP  is  the  entry  called  by  the 
application  to  process  a user  ”HEIP” 

command.  This  command  is  a ”HSG”  with 

the  receiving  userid  assumed  to  be  the 
•operator.  After  performing 

initialization  with  the  EKTE  macro,  this 
routine  locates  the  text  of  the  message 
to  be  sent  and  sends  it  to  the  operator 
by  calling  the  MTTHANG  subroutine  with  a 
userid  of  OPERATOR.  Return  to  the 
application  is  effected  with  the  EETN 

macro, 

32,  MTTBCST  routine 

This  is  the  routine  which  handles  the 
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(operator)  "BCSfT”  command.  It  is  ■ used 
to  send  a massage  to  all  attached  users* 
Upon  entry  and  after  the  text  of  the 
message  to  be  sent  is  verified,  the 
terminal  table  is  searched  for  active 
users,  lor  each,  the  MTTHRNG  subroutine 
is  called  to  hang  an  HCB  containing  the 
message  text  onto  the  MCB  chain  for  the 
user.  After  they  are  all  finished, 
return  to  the  caller  is  made  through 
(saved)  register  14, 

MTITFSEES  routine 

This  is  the  routine  uhich  processes 
either  the  user  or  operator  ’’USERS" 
command.  Entry  to  HTTOSEHS  is  for  the 
application  to  call  for  the  user 
command,  the  operator  command  causes 
entry  HTTDSER1  to  be  called. 

After  HTTDSERS  is  called,  normal 
initialization  is  accomplished  by  the 
ENTR  macro.  Eor  users,  a header  message 
is  composes  stating  the  time  and  that 
fcllouing  will  be  a list  of  KASlSIDs. 
This  is  sent  to  the  user  by  a call  • to 
HTTh’BITI,  Then  a column  pointer  and 
character  counter  are  set-up  and  control 
transferrs  to  the  common  accumulating 
routine. 

At  entry  to  MTTUSES1,  no  header  message 
is  sent  (it  is  assumed  the  operator 
knous  what  the  line  of  output  consists 
of) . Only  the  column  ‘ pointer  and 
character  pointer  are  initialized.  They 
are  different  for  the  operator  since  his 
message  has  to  start  with  the  time-stamp 
field.  Control  falls  through  to  the 
common  accumulation-  code. 

Mow  HTTUSEBS  adds  a border  ("#**")  • to 
the  left  part  of  the  line  if  a user 
message  is  being  composed.  It  then 
searches  the  terminal  table  for  active 
users,  moving  the  NASISID  of  each  one  it 
finds  into  the  print  line  with  trailing 
blanks  stripped  off  and.  separating  each 
MASISID  by  a blank.  Again,  if  a user 
message  is  being  processed,  the  border 
is  put  on  the  right-hand  end  of  the 
-message.  In  the  case  of  a user. 
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HtPTHEITl  is  used  to  send  the  list;  in 
the  case  of  the  operator,  the  HSG  macro 
is  used.  Return  is  either  through 
(saved)  register  14  (for  the  operator) 
or  via  the  RETN  mechanism  (for  a user 
call) . 

34.  HITFOBCE  routine 

!This  routine  is  the  processor  for  the 
(operator)  "FORCE”  command.  Upon  entry, 
it  merely  looks  for  the  RASISIR  which  it 
was  passed  in  the  terminal  table  (by 
calling  the  MTTGTUSE  subroutine)  and 
turns  on  the  force  flag  in  the  user’s 
TCT  (TCTPOlC)  if  the  HASISID  can  be 
located,  (The  user  will  actually  be 
forced  the  next  time  the  gueue-^scanner 
checks  through  the  terminal  table  for 
users  to  be  forced.)  Return  to  the 
caller  is  through  (saved)  register  14,  . 

35.  HTTHUSER  routine 

BTTSUSEE  contains  the  two  routines  to 
handle  the  user  and  operator  "NUSEBS” 
commands.  Entry  to  MTfNUSEB  is  for  the 
application  to  call  when  it  finds  the 
user  command.  Initialization  is 
performed  with  the  EKTB  macro.  Then  the 
number  of  users  is  picked-up  from 
HTTESEEf,  made  decimal  and  formatted 
into  a message.  The  message  is  sent  to 
the  user  via.  a call  to  HTTWEITi,  Return 
is  made  with  the  BETN  macro, 

HTTNUSB1  .is  the  entry  to  the  MTTNOSEE 
routine  for  processing  an  operator 
"RdSBRS”  command.  It  takes  the  number 
of  users  from  HTTOSEB#  and  formats  it 
into  the  appropriate  operator  message 
which  is  sent  via  the  HSG  macro.  Return 
from  this  section  is  through  (saved) 
register  14, 

36.  HIT-SHUT  routine 

This  routine  processes  the  HT/T  operator 
SHCTDORN  command.  After  it  is  called, 
it  examines  the  parameter  it  was  given. 
If  this  operand  is  defaulted,  the  value 
five  is  used  as  a default  (number  of 
minutes) . After  locating  or  defaulting 
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the  operand,  this  routine  converts  the 
EBCEIC  for  it  into  binary  and  converts 
the  number  into  milliseconds  for  use  by 
the  STIMEP,  A REAL  timer  (number  six) 
is  set  fox  the  resultant  interval  if  the 
operand  had  a positive  value.  If  the 
value  of  the  operand  was  zero,  the 
HTTENDI  routine  is  branched  to  directly 
to  effect  an  immediate  skutdown.  After 
the  timer  for  a non-zero  operand  has 
been  successfully  set,  the  caller  is 
returned  to  through  register  14. 

37.  MTTKILl  routine 

This  routine  is  used  to  sloppily  kill 
off  an  application  user.  If  the  user 
specified  by  the  operand  to  the  command 
can  be  located  (aTTGTUSH)  and  if  he  is 
in  control  (execution) , his  resuming 
VPS^J  from  the  attention  routine  is 
overlaid  to  transfer  control  to  memory 
location  as  scon  as  the  attention 
routine  transfers  control  hack  to  the 
point  of  interruption.  If  the  userid  is 
not  found  or  is  not  in  control,  an  error 
message  is  sent  to  the  operator  with  the 
MSG  facility.  Return  from  this  routine 
is  to  the  caller  through  register  14.,  , 

38.  MTTLIHIT  routine 

MTTLIHIT  is  the  processor  for  ■ the 
operator  LIMIT  command  which  can  be  used 
’to  limit  certain  application  facilities 
as  well  as  various  numbers  of  users 
allowed  onto  the  system  at  one  time. 
After  it  is  called,  this  routine 
attempts  to  find  out  what  manners  of 
operands  it  was  given.  If  the  first  of 
two  operands  is  not  two  characters  long, 
it  is  considered  to  be  a keyword  (for 
one  of  the  facilities)  and  the  table  of 
keywords  in  the  Monitor* s CSECT  is 
searched  to  find  a match.  (If  none  are 
found,  an  error  message  is  sent  to  the 
operator.)  If  one  is  found,  it  is 
pointed  to  and  control  is  passed  to  the 
number  scanning  code. 

If  the  first  of  two  parameters  is  two 
characters,  it  is  a class  name  (where 
class  is  the  first  two  characters  of  the 
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userid) . The  portion  of  tte  limit  table 
beyond  the  header  area  is  searched  until 
the  entered  class  name  is  located  or  the 
end  is  reached.  If  the  end  of  the  table 
is  reached,  the  entered  class  name  is 
added  to  the  bottom  and  pointed  to  for 
the  number  scanner.  If  the  entered 
class  name  is  found,  it  is  merely 
pointed  to  and  control  falls  to  the 
number  scanning  code. 

After  the  appropriate  class  name  is 
located,  the  second  parameter  is  scanned 
if  it  is  present.  (If  it  is  defaulted, 
the  number  32767  (infinity,  in  this 
case)  is  used  for  the  default.)  The 
number  is  scanned  left  to  right  digit  by 
digit.  Invalid  decimal  digits  cause  an 
error  message  to  be  sent  to  the  operator 
and  the  enterprise  to  be  abandoned. 
After  the  number  is  scanned,  it  is 
posted  in  the  slot  in  the  header  table 
(for  keywords)  or  after  the  class  name 
(for  class  names) ♦ Return  from  this 
routine  is  to  the  caller  through 
register  14. 

39.  HTTIEBTJG  routine 

This  routine  is  the  processor  for  the 
operator  DEBUG  command  and  consists  of 
two  instructions.  The  first  one  turns 
the  debug  switch  (DEBBGSTJ)  on  and  the 
second  one  returns  to  the  caller 
through  register  14. 

40.  STTBATIH  routine 

MTTDATIM  is  the  processor  for  the  user 
DATETIHE  command.  It  performs  its 
initiali’zation  and  entry  code  with  the 
EMH  macro,  fills  in  the  message  to  be 
sent  to  the  user  with  the  current  date 
and  time  with  the  TIME  macro  and  then 
calls  STTSEITI  to  send  this  message  to 
the  user.  It  then  returns  to  its  caller 
with  the  SETN  macro* 

41.  HTTEAIT  routine 

After  it  is  written  sometime  in  the 
future,  this  routine  will  be  the 
processor  for  the  user  WAIT  command, . 
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42.  ETTPGHS  routine 

This  routine  processes  the  operator 
PGMSTOP  command.  This  conunand  alters 
the  status  of  the 

program-interrupt-stopping  switch.  On 
entry,  this  routine  i:urns  off  that 
STJitch  and  checks  the  operand  to  the 
coamand  for  a length  of  two  (for  ”on”) . 
If  the  length  is  not  two,  the  routine 
returns  to  its  caller  through  register 
14,  If  it  is  two,  the  character  string 
CS  is  checked  for.  If  it  is  ON,  the 
switch  is  turned  on;  otherwise  the 
caller  is  merely  returned  to, 

43.  NTTNBHS  routine 

This  routine  processes  the  operator  NENS 
command.  After  it  is  called,  it  checks 
the  entered  operand  for  the  character 
string  OEF.  If  it  finds  it  as  the  first 
three  bytes  of  the  operand,  it  causes 
the  news  buffer  to  be  emptied  by  merely 
setting  its  length  to  zero.  If  the 
operand  is  real  news  text,  it  is  added 
to  the  bottom  of  the  news  buffer  if 
there  is  enough  room  in  it.  If  there 
• isn*t,  an  error  message  is  sent  to  the 
operator  and  the  command  is  ignored. 
After  the  text  is  moved  to  the  buffer, 
the  length  of  that  buffer  is  updated  and 
the  caller  returned  to  through  register 
14, 

44.  BTTBEC  routine 

This  is  the  routine  which  allows  the 
operator  to  manipulate  the  recording 
level  by  processing  the  BECOBD  command 
for  him,  (See  the  section  on  event 

recording  for  a description  of  what  the 
recording  level  actually  means.)  The 
numeric  operand  to  this  command  is 
processed  much  the  same  way  that  the 
number  for  the  LIHIT  command  is 
processed  except  that  an  error  message 
is  also  sent  to  the  operator  if  the 
number  is  greater  than  255,  If  the 
number  is  valid,  it  is  posted  as  a 
one-byte  value  in  the  field  NTTBECSW  in 
the  PSECT,  Return  to  the  caller  is 
through  register  14. 
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45.  HT5STAIS  subroutine 

This  routine  is  called  to  process  the 
operator  STATS  command.  All  it  does  is 
•verify  that  the  operand  to  the  command 
is  either  the  string  ”on”  or  ”off”  and 
set  a flag  in  the  PSECT.  Eeturn  is  to 
the  caller  through  register' 14. 

46,  MTTGTUSB  subroutine 

This  is  the  subroutine  uhich  is  called 
T?henever  somebody  wants  to  see  if  a 
particular  userid  is  currently  connected 
to  the  application,  A'fter  verifying  the 
'length  of  the  operand  (between  1 and  8) , 
the  operand  is  moved  to  a temporary  and 
right-padded  with  blanks.  Sow  the 
terminal  table  is  searched  top  to  bottom 
for  the  userid  passed  to  MTTGTDSB  (field 
TECUSEID  in  the  terminal  • table) , After 
(if)  the  entry  containing  the  userid  is 
found,  the  logged-on  field  in  the  TCT 
for  the  terminal  table  entry  is 
interrogated.  If  the  user  is  not  yet 
logged  on,  the  userid  is  considered 
invalid.  Valid  userids  are  indicated  by 
returning  the  terminal  table  entry 
pointer  and  a condition  code  of  zero. 
Invalid  userids  are  flagged  by  a 
condition  code  of  two  if  the  error 
return  address  (H6)  is  zero, . (In  both 
the  proceeding  cases,  the  caller  is 
returned  to  through  register  14.)  If 
there  is  an  error  return  address  (56 
ncn-zero)  , the  HTTBUSB  routine  is 
‘branched  to,  (It  will  make  use  of  the 
error  return  address  after  sending  the 
operator  an  error  message,) 

4-7,  HTTBPSE  subroutine 

This  subroutine  merely  sends  the 
operator  an  error  message  about  an 
invalid  userid  and  then  causes  control 
to  be  transferred  to  an  error  routine  by 
branching  through  register  six, 

48.  HTTBHSG  routine 

This  routine  does  the  same  thing  as 
MTTBUSE  except  that  the  error  message  is 
for  a missing  message. 
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'49.  MI-a-EEUPg;  routine 

This  routine  is  used  to  send  a message 
to  the  operator.  It  is  called  by  the 
HSG  macro  after  that  macro  located  the 
message  pointer  and  length.  This 
routine  first  puts  a time-stamp  field 
into  the  message  and  causes  it  to  be 
filled  in  by  use  of  the  TIHE  macro.  It 
then  posts  the  length  of  the  message  in 
core  and  uses  GATBE  or  GTWAB  to  send  it 
to  the  operator  depending  upon  whether 
or  not  response  fron  the  operator  is 
expected,  (If  response  was  expected^ 
the  receiving  field  is  blanhed  out 
before  text  is  read.)  - Return  from  this 
routine  is  to  the  caller  through 
register  14, 

50.  HTiTlME  routine 

This  is  the  routine  called  by  the  TIME 
macro  to  cause  an  EBCDTIHE  to  be 
performed  on  some  text.  . This  routine 
merely  moves  the  descriptors  of  the 
field  and  does  a register-form  EBCDTIME 
•on  the  field.  Return  is  to  the  caller 
through  register  14. 

51,  MTTMOVE  subroutine 

This  subroutine  merely  moves  text  from 
here  to  there  and  is  called  by  the  HOVE 
macro.  It  is  coded  to  be  as  quick  as 
possible  under  the  unaligned  text  case 
on  a 360/67,  It  makes  no  special 
efforts  to  detect  aligned  fields  so  it 
can  use  register  moves  on  them.  After 
the  text  specified  is  moved,  the  caller 
is  returned  to  through  register  14, 

52.  MTTTBAR  subroutine 

This  routine  is  called  by  the  TRAN  macro 
and  does  for  translating  text  the  . same 
thing  that  MTTHOVE  does  for  moving  text. 
Return  is  again  to  the  caller  through 
register  14, 

53,  MTTETRN  routine 

This  routine  is  actually  the  processor 
specified  for  ”SVC  63*’  instructions 
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which  are  issued  to  cause  transfer  of 
control  from  one  push-down  area  to 
another.  Since  this  routine  is  provided 
with  a push-down  area  by  the  system,  it 
can  merely  overlay  it  with  the  one  to 
’transfer  control  to.  After  doing  this, 
it  just  returns  through  the  linkage  to 
ihe  task  monitor  to  cause  the  desired 
push-down  area  to  receive  control, 

54.  HTTEESET  routine 

fhis  routine  is  called  from  the  TSS 
command  language  by  the  operator  when 
the  attention  processing  routine  is 
somehow  disconnected  (by  TSS) . After  is 
has  observed  type  I linkage  conventions 
to  get  itself  initialized,  it  merely 
re-specifies  the  attention  routine  In 
the  same  manner  as  the  HTTSTAET  defined 
it  to  start  with.  If  it  is  unable  to  do 
so,  MSG  is  nsed  to  send  indication  to 
the  operator.  In  either  case,  return  is 
to  the  caller  (TSS)  through  the  exit 
linkage, 

Eecording  Mechanism  Description 

The  event  recording  mechanism  is  incorporated 
into  the  Monitor  to  allow  events  and  some 
data  to  be  recorded  onto  the  (TSS)  system 
SIDE  (System  Internal  Performance  Evaluation) 
tape.  There  are  some  fields  which  may  be 
recorded  in  addition  to  the  data  area-  which 
may  *be  specified.  At  present,  the  things 
which  are  recorded  are  input /output  to  user 
terminals,  dispatches,  time-slice  ends, 
TfAITs  and  returns  from  WAITS,  Any  event  may 
be  recorded  in  the  Monitor  by  the  insertion 
•of  a SECOED  macro  at  the  event  to  be 
recorded,  (EECORD  is  described  below.)  Each 
event  recorded  must  have  a unigue  ”key”  so 
the  events  can  be  retrieved  from  the  tape 
with  identification.  Furthermore,  each 
recorded  event  (EECOBD)  must  have  a recording 
level  attached  to  it. . This  level  is  used  to 
determine  whether  or  not  the  event  is 
actually  going  to  be  recorded.  The  level 
corresponds  to  the  numeric  parameter  to  the 
EECOBD  operator  command.  If  the  event  level 
at  the  event  being  recorded  is  higher. than 
the  level  set  at  MTTEECSW  by  the  EECORD 
command,  the  event  is  not  recorded.  Thus, 
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all  the  recording  levels  are  higher  than  zero 
so  that  recording  can  be  disabled  by  entering 
zero  as  the  parameter  to  the  BECOED 
command* 

1*  BECOSD  macro  description 

This  macro  is  the  only  one  vhich  is  used 
by  record  events.  Its  format  is: 

TSVlI=,HTSVaL=,CPOTIM=,EEG=, 

DATa=,DATaiTH= 

where  KEY  is  the  key  number  to  be 
assigned  to  the  event  (they  actually 
start  at  4000  but  for  this  macro  we 
start  at  zero  and  it  remembers  what  the 
base  is)  and  lEVEl  is  the  level  to  be 
usefl  in  determining  whether  or  not  the 
event  is  to  be  recorded  as  discussed 
above,  TEfiH#  is  the  relative  terminal 
number  (TCTTEBH#  or  ENQPDV)  for  the  user 
in  question,  #DSEES  is  the  number  of 
'users  attached  to  the  application 

tHTTOSEB#).  TSVAl  is  the  user's 

time-slice  value,  usually  from  TCTTIHER, 
NISVAI  is  the  field  containing  the 
number  of  milliseconds  he  was 
dispatched  with  last  time  or  is  going  to 
be  dispatched  with  next  time,  taken  from 
TCINTS  and  CPUTIH  is  the  amount  of  CPU 
time  the  user  has  used  so  far,  taken 
from  TCTCPUTS,  BEG  is  a register  which 
may  be  recorded  if  you  wish;  it  is 
useful  for  dumping  return  codes  and 
suchlike,  DATA  is  the  pointer  to  a data 

area  which  you  need  recorded 
{input/oatput  text,  for  example)  and 
DATAITB  is  the  length  of  that  field, 
KEY  and  LEVEL  must  always  be  specified 
and  if  DATA  is  specified,  DATALTH  must 
also  be  specified.  Any  of  these  field 
may  be  specified  in  register  notation 
and  any  register  may  be  used.  Thus,. if 
you  have  the  elapsed  CPU  time  sitting  in 
a register,  you  could  code  CPUTIH={B7) 
instead  of  CPUTIM=TCTCPUTM,  In 

addition,  the  DATALTH  field  may  be 

either  an  address  of  a length  field,  a 
register  containing  the  length  or  an 
absolute  (or  undefined)  expression 

containing  the  length. 
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2,  Expanded  code 

The  RECOSD  macro  expands  code  to  collect 
rhe  fields  specified  into  either- 
registers  (DSEBIB,  TEEH#,  ftUSEBS,  TSVil, 
BTSVAL  and  CPUTIH)  or  into  an  area  in 
the  recording  area  itself  (DATA, 
DATAITH,  KEY).  Since  SITE  records  the 
registers  as  well  as  the  recording  area, 
they  are  used  to  • hold  as  much  of  the 
recorded  data  as  possible.  Future 
fields  will  have  to  he  put  into  the 
recording  area,  however,  as  there  are  no 
more  registers  available  for 
data-holding.  Code  is  also  expanded  to 
test  the  level  specified  against 
BTTBECSW  and  to  check  the  return  code 
frcm  SIPE  itself  to  make  sure  it 
intercepts  the  SVC  issued  to  activate 
it.  The  SVC  itself  is  in  the  beginning 
of  the  recording  area  (which  is  always 
pointed  to  by  register  1 during  EECOBDs) 
and  is  the  target  of  an  EXECUTE 
instruction  (so  that  SIPE  is  insured 
that  the  area  is  in  physical  core) . 

CODIHG  SPECIIICATIONS 

1„  Source  language 

TSS/360  -Assembler  language 

2,  Suggestions  and  Techniques 

Hot  Applicable 
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TOPIC  A. 2 - IHITIAL  EUTEY  BOTJTIflE 

A.  HOPDLE  NAME 

Initial  Entry  Eontine 
Program~ID  - EDBMTT 
Hodnle-ID  - DBMTT 

B.  ANALYST 

John  A*  Lozan 
Neoterics,  Inc, 

C.  HO DOLE  FDNCTION 

The  function  of  this  module  is  to  perform  allocations 
of  the  external  data  items  used  by  the  system.  It  also 
issues  the  initial  prompt,  which  is  used  to  determine 
which  BASIS  sub-system  the  user  wishes  to  invoke,  and 
then  calls  the  proper  module  for  that  sub-system. 

B.  DATA  EEQDIREHENTS 

1,  I/O  Block  Diagrams 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Hot  Applicable 

c.  Input  Files 
Not  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 
Hot  Applicable 

b.  On-line  Terminal  Displays 
Hot  Applicable 

c.  Formatted  Print-outs 
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Not  Applicable 
4,  Reference  Tables 

The  program  makes  use  of  the  following  fables: 

a.  TJSEBTAB 

b.  7EBBTAE 
PBOCESSING  BEQUIEENENTS 
■1*  Top  level  Flowchart 

See  Figure  2 
2,  Narrative 

a,  Initialize 

This  routine  initializes  the  interrupt  <ATTK 
and  END)  processing  routines  and  the  Pl/I 
error  handler.  It  allocates  and  initializes 
the  user  data  table.  The  program  also 
allocates  and  initializes  the  verb  table 
(including  user  specified  commands)  which  it 
uses  in  the  prompt  routine. 

b,  refine 

This  routine  performs  all  of  the  file  control 
block  allocations  and  initializations  for  the 
proper  operation  of  the  rest  of  the  NASIS 
system, 

c,  Prompt 

This  routine  sets  a temporary  END  condition 
handier  which  results  in  a new  prompt  on  an 
END  condition.  It  prompts  the  user  for  a 
command  and  searches  the  verb  table  for  a 
matching  entry.  If  no  match  is  found  a 
diagnostic  message  is  written  to  the  user  and 
the  prompt  is  re-issued. 

The  verb  table  entry  is  analyzed  and  if  an 
immediate  command  has  been  entered,  the 
program  branches  tc  the  routine  which 

processes  that  command.  Otherwise,  the 

program  optionally  establishes  a new  strategy 
and  then  calls  the  entry  point  of  the 
processer  for  the  command  entered,  Nhen 
control  is  returned  to  DBNTT,  the  user  is 


PAGE  51 


prompted  for  - the  disposition  of  -the  current 
strategy  and  it  is  either  renewed  or 
erased. 

Rhen  the  command  entered  has  been  completely 
processed,  control  is  passed  back  to  the 
prompting  routine.  The  entry  of  an  END 
command  causes  the  program  to  be 
terminated. 

E.  -CODING  SPECIIICATICNS 

1.  Source  language 
TSS/360  PI/I 

2.  Suggestions  and  Techniques 
Not  Applicable 


CRT 

TEBMINAL 


_ 

!! 

DBMTT 


TYPEWRITER 

TEBMINAL 


_ j 


Figure  1.  I/O  Block  diagram 
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TOPIC  i,3  - SINGLE  TEBaiHAL  TASK  HONITOR 

A.  MODULE  NAME 

Teriuinal  Support  - Single  Terminal  Task  Monitor 
Program-ID  - NASISX 
Hodule-IB  - MTTSDP-X 

Entry  Points  - NASISI,  MTTRRITE,  KTTREAD,  KTTWREAD, 
HTTGETIM,  MTTXTR,  MTTMUST,  HTTPASS,  HTTATTN,  MTTPGHIN, 
MTTSVC1,  MTTS7C2,  FIXATTN,  STTKA,  BTTKB 

B,  . ANALYST 

Franlc  Reed 
Robert  L.  Rutledge 
Neotexics,  Inc« 

C.  MODULE  EDRCTIONS 

1«.  Organization  Chart 
See  Figure  1 
2,  Overview 

The  function  of  this  module  is  to  • provide  the  MTT 
monitor  services  to  the  non-HTT  user  of  the  NASIS 
system,  allowing  NASIS  to  he  invoked  in 
* 'standalone* * mode, 

D,  . DATA  SEQUIREMENTS 

1,  I/O  Block  Diagram 
See  Figure  2 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  applicahls 

b.  Punched  Card  Input  Files 
Not  applicable 

c.  Input  Files 
LIS RIDS 

d.  On-line  Terminal  Entries 


PAGE  55 


Th€  user  enters  his  NASIStID  and 
secux'ity-code  when  prompted. 

3,  Output  Data  Sets 
^Iot  applicable 

4.  Eeference  Tables 

a.  External  Tables 

1 . HTTDTAB 

2.  HTTLOAB 

h.  Internal  Tables 
Not  Applicable 


PROCESSING  REQTIISiaERTS 
1.  Top  leirel  Plowcharts 
a.  Entry  Points 

1.  NASIsr  - See  Pigure  3 

2.  MTTREITE  - See  Figure  4 

3.  MTTREAD  - See  Pigure  4 

4.  HTTNEEAD  - See  Figure  4 

5.  NTTGETIH  - See  Figure  5 • 
•6.  HTTXTE  - see  Pigure  6 

7.  HTTHTJST  - See  Pigure  7 

8.  MTTPASS  - See  Figure  8 

9.  HTTATTN  - See  Figure  9 

10. -  MTTS7C1  - See  Pigure  10 

11.  HTTPGHIN  - See  Figure  11 

12.  HTTSVC2  - See  Figure  12 

13.  FIXAfTH  ■’  See  Figure  13 

14.  HTTKA  - see  Figure  14 

15.  HTTKB  - See  Figure  14 


his 
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Narrative 

a.  Entry  Pcint  BASIS  1 

This  section  of  code  begins  a BASIS 
application  in  standalone  mode.  , The 
preliminary  functions  it  performs  include 
specifying  interrupt  routines,  initializing 
timers  and  checking  the  user’s  userid  and 
security  code.  After  these  have  been 
successfully  completed,  the  location  of 
EBBMTT  is  retrieved  from  the  table  MTTIOAD 
and  control  is  passed  to  it.  On  return,  the 
interrupt  routines  are  deleted  and  control  is 
returned  to  the  caller  (terminal  user) . 

b.  Entry  Points  HTTBEAD,  HTTHEITE  and  0TTNBEAD 

These  routines  are  the  ones  which  do  actual 
I/O  to  the  user  terminal.  This  is 
accomplished  hy  an  ENTEB  to  the  GATE  junction 
using  a control  block  .initialized  by  the 
calling  program. 

A TWAIT  is  executed  for  write-only  outputs  to 
insure  a coherent  interchange  should  the  user 
press  the  attention  key  before  the  output  is 
complete.  On  return  from  all  I/O  functions, 
the  GATE  return  code  is  placed  in  register  15 
and  control  is  passed  to  the  caller. 

c.  Entry  Point  HTTGETIH 

HTT6ETIH  returns  elapsed  connect  and  CPO  time 
to  its  caller.  All  times  are  kept  via  the 
EEDTIH  AND  XTBTH  macros. 

a.  Entry  Point  HTTXTE 

This  routine  returns  information  about  the 
terminal  user  to  its  caller.  Specifically, 
the  userid,  security  code,  taskid,  HT/T  and 
conversational  mode  flags  are  returned, 

e.  Entry  Point  HTTHOST  ‘ ~ - . 

This  entry  point  is  not  required  in 
standalcne  mode,  hence,  it  is  a no-op. 

f.  Entry  Point  MTTPASS 

MTTPASS  prompts  the  terminal  user  for  his 
password  (security  code)  and  returns  the 
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response  to  its  caller. 

g«  Entry  Points  HTTKA  and  MiTKB, 

These  routines  are  used  to  get  the  user  into 
either  KA  or  KB  mode.  The  OBEY  macro  is 
utilized  to  accomplish  this  feat. 

h.  Entry  Point  FIXATTH 

This  entry  point  is  called  by  a terminal  user 
to  re-activate  the  attention  routine  whenever 
it  goes  away  (which  occurs  frequently  during 
debugging) . The  attention  routines  are 
deleted  and  re-specified  to  TSS  and  control 
is  returned  to  the  user. 

i.  Entry  Point  BTTATTH 

This  routine  gains  control  of  attention 
interrupts  from  the  system  and  passes  then 
along  to  the  attention  routine  specified  in 
the  MTTIOAD  table.  Two  savereas  are  reserved 
in  the  KASISX  PSSCT  to  hold  the  interrupted 
registers  and  VPSIJ. 

On  entry  the  interrupted  registers  and  VPSH 
are  moved  to  one  of  the  saveareas  and  the 
interrupt  is  dequeued.  Then,  the  processor 
is  called  with  register  1 pointing  to  the 
savearea.  On  return  from  the  processor, 
J5TTSVC1  is  invoked  to  return  control  to  the 
point  of  interrupt. 

■j.  HTTSVC1 

This  routine  moves  the  registers  from  a 
HASISX  savearea  to  the  system  savearea 
pointed  to  by  register  0 (zero) . Control  is 
returned  to  the  system,  which  loads  the  moved 
registers  and  VESS  and  passes  control  to  the 
point  where  execution  was  interrupted  by  the 
user. 

h.  MTTPGHIK 

This  routine  is  called  by  the  system  whenever 
a program  interrupt  occurs  within  the 
application.  The  user  is  notified  and  the 
interrupted  registers  are  displayed  at  the 
terminal.  Next,  the  user  is-  prompted  via  the 
CLIC  macro.  If  his  response  is  ”G0’*, 
control  is  returned  to  the  point  of  interrupt 
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by  invoking  entrj  point  HTTSVC 
i.  STTS7C2 

Ibis  rontine  moves  bbe  registers  active  at 
the  time  of  a program  interrupt  from  a NASIS2 
savearea  to  the  system  savearea  pointed  to  by 
register  0 (zero) • Control  is  returned  to 
the  system,  which  in  tarn  returns  control  to 
the  point  of  interrupt. 

. P,-  CODING  SPECITICATIOHS 

1.  Source  language 

TSS/360  Assembler  language. 

2.  Suggestions  and  Techniques 
Not  Applicable 


4 


TSGETia 


i’igure*.  1»  Terminal  Support  Organization  Chart 


Figure  2,  l/O  Block  Diagram 


Figure  3 . Entry 
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Figure  5 


Entry  Point  MITGETDI 
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Figure  6.  Entry  Point  MTTXTR 


Figure  7.  Entry  Point  MTTMUST 


Figure  8.  Entry  Point  liTTPASS 


Figure  10.  Entry  Point  HTTSVCI 
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Figure  11.  ; MTTBGMIN 
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Figure  12.  Entry  Point  MTTSVCZ 
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Figure  14.  Entry  Point  M.TTKA  and  MTTKB 
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50PIC  B.1-  - EXEC02I7E  EEE^PSOCESSOB 


A.  MODULE  NAME 

Data  Base  Executive  - Preprocessor 
Program-ID  - DB 
Moaule-ID  - DB 

B.  ANALYST 

Garth  B,  Nymaji 
Neoterics,  Inc. 

C.  MODULE  FUNCTION 

DB  analyzes  Data  Base  PI-/I  language  extension  (DBPL/I) 
statements  and  generates,  in  their  place,  in  a source 
program,  PL/I  statements  for  communication  with  the 
Data  Base  Executive  (EDBPAC  OS  EDBLIST) « Diagnostic 
comments  are  generated  for  errors  that  can  be  detected 
by  DB  during  preprccessing, 

D.  DATA  EEQOIEEHENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 

Job  control  parameters  for  operation  under 
TSS  are  those  required  for  PL/I 
precompilation  and  immediate  compilation, 
Defer  to  the  appropriate  IBM  PL/I 
Programmer’s  Guide  <Form  C28-20^49  for  TSS). 
The  Pl/I  compiler  parameters-MACBO,  S0UECE2, 
and  COME  (among  others)  are  specified  to 
indicate  that  precompiling,  precompiler  input 
listing  and  compiling  are  desired. 

b.  Punched  Card  Input  Files 
'1 . DB  Text 

The  DB  Text  deck  is  text  for  insertion 
into  the  source  program  as  a result  of  a 
% INCLUDE  DB;  statement  in  the  source 
program.  This  text  is  composed  of  the 
source  statements  of  the  DB  preprocessor 
function  procedure,  itself,  and  any  PL/I 
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statements  to  be  tmconditionally 
inserted  at  the  % INCIODE  point  in 

the  source  program*  DB  Text  is  coded  as 
specified  in  this  report,  formatted 
according  to  Pl/I  source  language 
standards  and  catalogued  once  in  a data 
set  for  compile-time  use  by  all  programs 
using  BB. 

2.  Source  Deck 

'The  SOUECE  Deck  is  any  • Pl/I  spurce 
program  using  DB  for  its  DBPl/I 
statements.  It  is  prepared  according  to 
the  DBPl/I  User’s  Manual  (DWB  Section  V, 
Topic  B.2)  to  access  a self-describing 
data  base  and  formatted  according  to 
PD/I  source  language  standards, 

c.  Input  riles 

DB  Text  is  catalogued  as  a member,  named'  DB, 
of  a partitioned  direct  access  data  set  for 
retrieval  by  the  IBM  Pl/I  precompiler.  The 
data  set  is  accessed  via  ddname  LISEHAC, 

d*  On-line  Terminal  Entries 
Ect  Applicable 

Output  Data  Sets 

a.  Output  Piles 

The  object  module  consists  of  the  relocatable 
machine  instructions  and  constants  generated 
by  the  Pl/I  compiler  for  the  source  program. 
It  is  stored  as  a member  of  a program  library 
(Partitioned  data  set)  for  subseguent  loading 
by  the  TSS  system  loader, 

b.  On-line  Terminal  Displays 
Dot  Applicable 

c.  Pcrmatted  Print-outs 

1,  Precompiler  listings 

Two  precompiler  listings  are  produced: 
a source  listing  before  pxecompilation, 
and  any  precompiler  diagnostics  (these 
diagnostics  are  any  errors  in  the  use  of 
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preprocessor  Pl/I,  no-fc  DBPL/X) • The 
appropriate  IBM  PI/I  Programmer’s  Guide 
explains  the  listing  formats. 

2»  Compiler  listings 

The  compiler  listings  include  an 
intermediate  source  listing  <betu€en 
precompiling  and  compiling)  • and  any 
compiler  diagnostics.  Any  errors  in  the 
use  of  PBPI/I  generate  diagnostic  PL/I 
comments  in  the  intermediate  source 
listing.  Serious  DBPL/1  errors  may 
result  in  compiler  diagnostics, 
-particularly  for  undeclared  qualified 
names  when  DB  has.  suppressed  automatic 
generation  of  a declare  statement.  The 
appropriate  IBH/I  Programmer’s  Guide 
explains  the  listing  formats. 

d.  Punched  Card  Output  Files 

Hot  Applicable 

4.  , Reference  Tables 

HFCB  - Mainline  file  control  block,  . 

See  Section  III,- Topic  B..  4,  of  the  DBB. 

DBPL/I  - Diagnostic  comments. 

See  Section  III,  Topic  B.1,  of  the  DHB, 

DBPL/I  - DBPAC  Interface, 

See  Section  III,  Topic  B.2,  of-  the  DHB.. 
DBPL/I  - DBLIST  Interface. 

See  Section  III,  Topic  B.10, 

PPOCESSIHG  EEQDIHEMENTS 

'1,  Top  Level  Flowchart 

See  Figure  2 

2,  Narrative 

a.  Top  Level 

The  mainline  P1-/I  source  program  is  required, 
according  to  the  DBPL/I  User’s  Manual  (DIB 
Section  y.  Topic  B.2),  to  have  a%  INCLUDE  DB1 
statement  once  in  the  program  before  all  DB 
preprocessor  function  references.  This 
statement  directs  the  PL/I  precompiler  to 
take  text  from  member  DB  of  the  partitioned 
data  set  accessed  via  ddname  LISBMAC  and 
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XBcorporai:e  it  into  the  source  prograta.  (See 
the  I/O  Block  Diagram  in  Eigure  1.). 

3he  BB  text  includes  the  following 
statements: 

ON  FINISH  GO  TO  FINISH; 

for  "automatic”  data  base  file  closing. 
BEPL/I  reguires  that  the  PI/I  FINISH 

ON-condition  be  reserved  for  this  purpose. 

The  DB  text  declares  and  activates  the  DB 
preprocessor  name  by; 

% DECIAEE  DB  ENTEY (CHABACTEE) 

EETURNS (CBAEACTEE) ; 

The  DB  text  following  the  end  of  the  DB 
preprocessor  function  procedure  invokes  DB 
once  as  follows: 

DB  (INITIALIZE) 

This  statement  is  a special  function 

reference  to  be  recognized  by  DB  as  the  first 
reference  (directing  DB  to  initialize 
itself) • 

The  remainder  of  this  narrative  specifies  the 
DB  preprocessor  function  procedure  which  is 
depicted  in  the  Top  Level  Flowchart  in  Figure 

2. 

BB  receives  one  argument  from  a preprocessor 
function  reference:  a varying  length 

character  string  consisting,  in  general,  of 
labels,  comments,  valid  DBPL/I  statements 
and,  possibly,  invalid  text.  DB’s  objective 
is  to  analyze  the  argument  and  generate  a 
varying  length  character  string,  called  the 
"generated  text”,  consisting  of  valid  PL/I 
labels,  comments  and  PL/I  statements  for 
communication  with  the  Data  Base  Executive. 

If  the  special  argument,  ’INITIALIZE*,  is 
received,  (i.e.,  the  first  reference  to  DB) , 
the  Initialize  DB  routine  is  performed  and  a 
comment,  such  as: 

/*  DB001  INITIALIZATION  COMPLETE.  */ 

is  returned  for  insertion  into  the  source 
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program  and  DB  is  terminated.  Otherwise,  the 
Argument  Initialization  routine  is 
performed, 

Eollowing  the  Argument  Initialization  routine 
EB  is  logically  between  DBPL/I  statements  in 
its  processing  of  the  argument,'  The  Find 
Subargument  routine  is  performed  there.  If 
it  finds  the  right  parenthesis  at  the  end  of 
the  argument,  the  generated  text  is  returned 
for  insertion  into  the  source  program,  and  DB 
is  terminated.  If  Find  Subargument  finds  an 
inter-statement  comment,  a statement  label, 
or  a null  statement  (simply  a semicolon) , 
then  the  subargument  is  concatenated  to  the 
right  end  of  the  generated  text  (l,e«, 
’’passed  through”  to  the  intermediate  source 
text)’,  and  preprocessor  control  is 
transferred  bach  to  the  inter-statement 
point.  Otherwise,  the  Process  Statement 
routine  is  performed,  and  preprocessor 
control  is  transferred  back  to  the 
inter-statement  point. 

Diagnostic  Comment  Generation 

B her ever  this  narrative  specifies  the 
generation  of ' a diagnostic  comment,  the 
following  specifications  apply,  A diagnostic 
comment  is  concatenated  to  the  right  end  of 
the  generated  text  for  insertion  into  the 
intermediate  source  program.  If  the 
diagnostic  is  for  an  error,  the  precompiler 
count  of  diagnostics  is  incremented.  If  more 
than  four  errors  are  detected  in  one  DB 
reference  further  processing  of  that 
reference  is  stopped  to  prevent  the 
possibility  of  unpaired  quotes,  parentheses 
or  comment  delimiters  looping  the 
preprocessor.  A diagnostic  has  the  following 
general  format; 

/*  DBnnn  diagnostic-message, 

The  ”BB”  preceding  the  message  number 
indicates  that  the  comment  was  generated  by 
the  DB  preprocessor.  The  three-digit  message 
number  guides  the  user  to  a more  detailed 
explanation  of  the  message  ‘ which  is 
documented  in  the  DUB  Section  III,  Topic 
B,  1, 


Initialize  DB 


P4GI  78 


Precompiler  variables  fox  file  attributes, 
file  usages  and  diagnostic  counts  are 
appropriately  initialized.  These  variables 
are  subsequently  set  or  incremented  as  DBPL/I 
statements  are  processed  and  are  examined 
nhen  the  finish  statement  is  processed,  A 
precompiler  indicator  is  set  to  indicate  that 
the  FIKISH  statement  has  not  yet  been 
processed, 

d.  argument  Initialization 

' The  argument  is  examined  to  find  the  left 
parenthesis  at  its  beginning.  If  any  other 
non- blank  character  is  found,  a diagnostic 
comment  is  generated  and  DB  is  terminated,  a 
precompiler  variable  pointing  to  the  "current 
argument  character"  is  initialized  to  point 
to  the  character  following  the  beginning  left 
parenthesis.  The  generated  text  is 
initialized  as  one  blank  character. 

e,  Find  Subargument 

a subargument,  as  used  in  this  specification, 
is  a substring  of  the  argument  that  is  one  of 
the  following  classes  of  syntactic  units; 

1,  The  right  parenthesis  at  the  end  of  the 
argument, 

2,  a label,  including  its  colon. 

3,  an  inter-statement  PL/I  comment,  . 

4,  a Hull  statement  consisting  only  of  a 
semicolon, 

5,  a EBPL/I  statement  terminated  by  a 
semicolon, 

6,  a syntax  error.;  i.e,,  none  of  the 
above, 

a class  (5)  suhargument  may  contain  paired 
parenthesis  (possibly  nested)  or  string 
constants  enclosed  in  string  quotes,  a class 
(6)  subargument  will  be  terminated  by  a 
semicolon  if  one  Is  found  but  will  never 
include  the  right  parenthesis  at  the  end  of 
the  argument. 

The  Find  Subargument  routine  is  used  at  the 
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inter- statement  point  in  the  Top  Level 
Tlowchart.  The , argument  is  examined 
beginning  at  the  current  argument  character 
and  ignoring  leading  blanhs  to  find  the  next 
subargument*  fi  precompiler  variable  pointing 
to  the  beginning  character  of  the 
subargument , and  another  indicating  its 
length  in  characters,  is  set*  The  current 
argument  pointer  is  advanced  to  point  to  the 
character  following  the  subargument. 

Process  Statement 

This  routine  analyzes  a single  DBPL/I 
statement  body  (i,e»,  apart  from  any 
statement  labels) , generates  suitable  PL/I 
statements  for  communication  with  the  data 
base  executive  and  returns  preprocessor 
control  to  the  inter-statement  point.  The 
PL/I  statements  and  comments  that  are 
generated  are  concatenated  to  the  right  end 
of  the  generated  text  string  for  subseguent 
insertion  into  the  intermediate  source 
program, 

J diagnostic  comment  containing  the 
suhargument  and  any  intra-statement  comments 
is  generated  for  documentation  and  for 
reference  in  case-  of  other  diagnostics.  If 
the  FINISH  statement  has  already  been 
processed  or  if  the  suhargument  -has'  a syntax 
error,  an  appropriate  diagnostic  comment  is 
generated,  and  control  is  returned  to  the 
inter- statement  point. 

If  the  Find  Keyword  routine  does  not  find  a 
keyword  that  identifies  a DBPL/I  statement, 
then  a diagnostic  comment  is  generated  and 
control  is  returned  to  the  inter-statement 
point.  If  the  keyword  identifies  a SET, 
FINISH,  FRF-E  Or  ON  statement,  control  is 
transferred  to  . the  relevant  specific 
statement  routine.  The  Find  File  clause 
routine  is  performed  if  the  second  clause  is 
not  a FILE  clause  then  a diagnostic  comment 
is  generated,  and  control  is  returned  to  the 
inter-statement  point.  The  Find  File  routine 
is  performed,  and  control  is  transferred  to 
the  relevant  specific  statement  routine, 

1,  Find  Keyword  Routine 

A clause,  as  used  in  this  specification. 
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is  a substring  the  subargument  thai 
is  one  of  the  following  classes  of 
syntactic  units: 

-’the  semicolon  at  the  end  of  the 
subargument, 

-a  comma  separating  DBPl/I 

substatentents; 

e«g,,  in  a multiple  OPEN, 

-a  keyword  with  an  associated 
parenthesized  argument, 

-a  keyword  without  a parenthesized 
argument, 

a keyword-with-arguraent  clause  may 
contain  paired  parenthesis  (possibly 
nested) , or  string  constants  enclosed  in 
string  quotes. 

The  Find  Keyword  routine  is  used  to  find 
the  keyword  that  will  identify  a 
statement  to  branch  to  the  specific 
statement  routines, 

-2,  Find  File  Soutine 

The  Find  File  subroutine  extracts  the 
file  name  from  a given  FILE  clause.  If 
the  file- name  is  not  a valid  PL/I 

external  name,  a diagnostic  message-  is 
generated,  and  the  statement  abandoned 
by  control  being  transferred  to  the 
inter-statement  point.  Otherwise,  the 
precompiler’s  file  table  is  searched  to 
determine  if  the  file-name  has  been  used 
previously  in  the  program.  If  it  has 
not,  a new  entry  is  appended  to  the  file 
table.  In  either  case,  a precompiler 
variable  is  set  to  indicate  the  current 
file,  and  control  is  returned  to  the 
point  from  which  Find  Pile  was 
invoked,  . 

3,  Specific  Statement  Eoutines 

Each  specific  statement  routine  examines 
the  statement  from  left  to  right  until 
the  semicolon  is  found.  {The  CLOSE  and 
OPEN  statement  routines  recognize  a 
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coffiaa  as  separating  substatements  and 
loop  accordingly)  . The  Iceywcrds  are 
verified  for  correct  spelling  and  order. 
The  FEEE  LIST  routine  for  specific  lists 
recognizes  a comma  separating 
list- pointers  and  loops  accordingly. 
Soutines  that  process  a statement  having 
a JIELD  danse  recognize  a comma 
separating  field-name  expressions,  find 
the  corresponding  element  in  tbe  FHOH  or 
INTO  clause  and  loop  accordingly.  If 
any  error  is  detected,  a diagnostic 
comment  is  generated,  and  the  statement 
abandoned  by  control  being  transferred 
to  the  inter-statement  point.  . 

for  those  statements  having  a EIIE 
clause,  the  precompiler’s  file  table  is 
posted  to  record  the  file  usage  (for 
analysis  in  the  FINISH  routine) . 

Following  successful  analysis,  each 
specific  statement  routine  generates 
PL/I  statements  for  communication  ■ with 
the  PBPAC  or  DBLIST  executive  and  then 
loops  bach  either  to  process  another 
FXEI-D  or  FBEE  LIST  element,  to  process 
another  OPEN  or  CLOSE  substatement,  or 
to  the  inter-statement  point.  Special 
processing  for  the  ON — and  FINISH 
statements  is  specified  after  the 
general  specifications  for  • all  other 
specific  statement  routines. 

For  those  statements  having  an  entry  in 
the  DBPL/I  - DBPAC  Interface  table 
(Section  III,  Topic  E, 2,  of  the  DWB) , an 
assignment  statement  is  generated  in  the 
following  format: 

filename, OPIEATI OH  = ’operation’s; 

For  example,  when  processing  the 
following  argument; 

LOCATE  FILE(SAt!PF)  KEYFEOH  (EEC#)  ; 

The  following  assignment  is  generated; 

SAHPF.OPEEATION  = ’11010000’B; 

For  statements  having  a FIELD  clause, 
the  operation  assignment  need  only  be 
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generated  once  for  the  statement,  even 
if  it  contains  multiple  field'  names. 

Tor  an  OPEN  statement  having  a TITLE 
clause  the  following  assignment  is 
generated; 

filename, OHTIIE  = title-expression; 

If  it  has  no,  TITLE  clause  the  following 
is  generated; 

filename. ONFILE  = 'filename*; 

Tor  an  OPEN  statement  having  an  "access" 
option  and/or  a "function"  option,  a 
hit-string  value  is  assigned  to 
filename,  ATTEIBTJTES  according  to  the 
definition  of  a Mainline  File  Control 
Block  (described  in  Section  III,  Topic 
B.i|  of  the  DNB) ; otherwise,  the 
following  .assignment  is  generated  for'  an 
OPEN; 

filename. FUNCTION  = *10*B; 

For  each  field-name  in  a FIELB  clause, 
an  assignment  statement  is  generated  as 
follows; 

filename, ONFIELD  = fieldname; 

IShere  the  field-name  may  be  an 
expression,  for  example,  when  processing 
the  following  argument: 

GET  FILE(EXAHP)  FIELD  (» DATEPDB* ) 

INTO  (DP)  ; 

The  following  assignment  is  generated; 

EXAHP. ONFIELD  = 'DATEPUB*; 

For  those  statements  having,  an  entry  in 
the  DBPl/I  - DBPAC  Interface  table,  a 
CALL  statement  is  generated  in  one  of 
the  following  formats,  depending  on 
whether  the  "Argi"  and  "Arg2"  columns  of 
the  table  have  entries: 

CALL  entrypoint  (argi)  ; 

CALJ  TVT>oi  n+  /arn1-  a'ra9\  ?• 
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caXL  entry  point  (argi,  arg2,^  arg3)  ; 

For  example,  when  processing-  this 
statement: 

lOCSTE  FIlE<BaHPT)  KEYFROH  (EEC#)  ; - 

This  CAII  is  generated; 

CAIX  0EPACFV  (SAHPF,  EEC#); 

For  those  statements  having  an  entry  in 
the  EBPI/l-DBlIST  Interface  Table 
(Section  III,  Topic  B.10),  a CALL 
statement  is  generated  according  to  the 
tatle. 

The  ON  statement  routine  examines  the 
second  clause.  If  an  EEEOEEILE  clause 
is  found,  the  Find  File  subroutine  is 
performed.  The  statements  shown  below 
at  the  right  are  generated  for  the  ON 
statement  shown  at  the  left. 

OH  EEEOEFIIE  (f)  GO  TO  label; 

f .EESOE.EOOTINE  = label; 

f. SYSTEM  = *0«B; 

OH  EEEOEFIIE (f)  SYSTEM; 

f. SYSTEM  = M*B; 

OH  IISTEBEOB  GO  TO  label; 

LISTEBH.EEROE.BOOTIHE  = label; 

IISTEES. SYSTEM  = *0»B; 

OH  LISTEIEOS  SYSTEM; 

IISTEBB. SYSTEM  = *1*B; 

The  FINISH  statement  routine  sets  a 
precompiler  indicator  to  indicate  that  a 
FINISH  statement  has  been  processed. 
Also,  the  following  statement  is 
generated; 

FINISH:  ON  FINISH  SYSTEM; 

Then  each  entry  in  the  precompiler’s 
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file  table  is  analyze!.  If  the  file  vas 
use!  inconsistently  in  the  program,  a 
diagnostic  comment  is  generated  and  the 
next  file  analyzed.  Otherwise,  a 
Mainline  rile  Control  Block  (MFCB) 
declaration  is  generated,  using  the 
file-name  as  the  major  structure  name 
and  as  the  initial  value  of  the  title. 
Any  file  attributes  implied  by  the  usage 
of  the  file  are  generated  into  the 
initial  value  of  the  filename. ACCESS  and 
filename.  ITJHCTIOB  fields.  Statements 
are  generated  to  "automatically”  CLOSE 
the  file,  jnst  the  same  as  for  a CLOSE 
statement. 

After  all  files  have  been  analyzed,  the 
following  statement  is  generated? 

BETBBM; 

In  all  programs,  a declaration  of  the 
entry  points  to  the  Data  Base  Executive 
(DEEAC)  is  generated. 

In  all  cases,  a summary  diagnostic 
comment  is  generated  giving  the  number 
of  DB  diagnostic  error  comments  in  the 
program, 

CODING  SPECIFICATIONS 

1,  . Source  Language 

The  IB  preprocessor  function  procedure  is  coded 
using  the  preprocessor  PL/I  statements  permitted 
in  preprocessor  PL/I  procedures. 

Statements  to  be  INCLUDEd  or  generated  into  the 
intermediate  source  program  are  coded  using 
PL/X  • 

2.  Suggestions  and  Technignes 

The  DE  preprocessor  function  procedure  is  coded  in 
a modular  manner  so  that  the  syntax  analysis  of 
the  argument  is  separate  from  the  generation  of 
statements.  This  modularity  will  allow  much  of 
the  DB  coding  to  he  usable  for  any  other 
extensions  to  PL/I  that  may  be  designed,  such  as  a 
Terminal  Support  PL/I  language  extension. 

The  coding  of  the  specific  statement  routines  are 
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”tabl€-ariven”  where  possible  to  facilitate  any 
future  changes  in  the  generated  text  for  a 
particular  statement. 


Figure  1.  - I/O  Block  diagram. 


I . ) 


Figure  Z -Toplevel  flowchart. 
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TOPIC  B,2  - DATA  BASE  EXECUTIVE  EXECUTION  PROCESSOE 


A..  MODULE  NAME 

Data  Base  Executive  ExecutioB  Processor 
Program-ID,-  BDBPAC 
Sodule-ID  - DBPAC 

Procedure  Entry  Point  ^control  section  name).:  IfPIELD 
Other  Entry  Points  - #XBEP,DBPACPE,DBPACEP 

DBPACPP,DBPACFV,DBPPLDT 


B.  ANALYST 

Garth  E»  Wyman 
Neoterics,  Inc. 

C.  MODULE  FUNCTION 

SDBPAC  executes  all  data  base  input/output  for  mainline 
programs. 

Mainline  PL/I  programs  are  written  with  DBPL/I 
statements  for  data  base  input/output.  (See  the  DBPL/I, 
User’s  Guide,  Section  8,  Topic  B. 2) . These  statements 
are  processed  during  compilation  and  CALL  statements 
are  generated  (according  to  the  DBPL/I-DBPAC  Interface 
Specification,  Section  3,  Topic  B.2).  The  first 
parameter  passed  in  a CALL  to  BDBPAC  is  a Mainline  Pile 
Control  Block  (see  Section  3,  Topic  B. 4) , 

SDBPAC  executes  the  request  indicated  by  the  operation 
code  in  the  HFCB,  For  physical  input/output  operations 
it  CALLS  appropriate  entries  in  the  HDBTSSIO  module. 
Whenever  BDBPAC  detects  either  a logical  error  or  a 
physical  Input/output  error  it  posts  an  error  code  in 
the  MFCB,  (See  DEPAC  Error  Codes,  Section  3,  Topic 
B.3) , 

D.  DATA  REQUIBEHENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

The  BDBPAC  module  does  not  do  any  terminal 

input/output  or  print  any  reports. 

2.  Input  Data  Sets 

When  a mainline  program  is  accessing  the 
descriptor  data  set  of  a data  base,  ’’descriptor 
descriptor”  tables  coded  in  BDBPAC  are  used 
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instead  of  an  input  descriptor  data  set, 

3. , Output  Data  Sets 

The  descriptor  data  set  is  updated  as  part  of  OPEN 
and  CLOSE  processing  (setting  and  reseting  tte 
MNTNABLE  and  ENTNIN6  svitcies) . 

4,  Seference  Tables 

a*  BBPL/I  - BBPAC  Interface  (see  Section  3, 
Topic  E.2) 

b,  BBPAC  Error  Codes  (see  Section  3,  Topic  B,3) 

c.  Mainline  file  Control  Block  (see  Section  3, 
Topic  B,4) 

d»  List  Structure  (see  Section  3,  Topic  B,5) 

e.  . Dataplex  Descriptor  file  (see  Section  3^ 

Topic  B.7) 

f.  Inverted  Index  format  (see  Section  3,  Topic 
D,5) 

g.  FLDTAB  Table  (see  Section  3,  Topic  P, 10) 
PBOCESSIN6  EEQDIEEBENIS 

1*. , Top  Level  flowchart 
See  Figure  2 

2. . Narrative 

a,  Eeceive  Control 

The  entries  at  the  beginning  of  the  module 
are  described  here;  entry  DBPLBT  is  described 
in  paragraph  "f”  below.  All  entries  receive 
a Mainline  File  Control  Block  (HFCB)  -as  their 
first  parameter.  RDBPAC  treats  the  HFCB  as 
a simple  parameter;  that  is,  BBBPAC  does  not 
know  that  the  HFCB  is  a CONTROLLED  structure 
allocated  by  the  mainline;  BBBPAC  never 
ALLOCATES  or  FEEEs  an  HFCB. 

Fox  the  #FIELD  and  #XBEF  function  entries,  an 
appropriate  operation  code  is  posted  in  the 
HFCB  and  the  second  parameter,  which  is  a 
file  name,  is  copied  into  the  HFCB.  This  is 
necessary  because  the  function  references  in 
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the  mainline  Tiave  not  l)een  expanded  by  the  DB 
preprocessor. 

The  rBPflCFK  entry  handles  a user  record  in 
the  form  of  a character  string  as  its  second 
parameter. 

The  BEPfiCPP  and  DBPACF?  entries  both  handle  a 
user  list  pointer  as  their  second  parameter. 
BBPACPF  additionally  accepts  a user  subscript 
as  its  third  parameter.  A switch  indicating 
the  absence  or  presence  of  a user  subscript 
is  set. 

The  BBPACFY  entry  handles  a user  field  value 
in  the  form  of  a varying  length  character 
string  as  its  second  parameter.  The  B3PACFV 
entry  is  also  used  for  all  statement  calls 
that ' only  pass  an  MFCB  without  a second 
parameter. 

b.  Common  Code 

Handling  for  PL/I  errors  that  may  occur  in 
HDBPAC  is  initialized  so  that  they  will  canse 
a jump  to  paragraph  ”m”  below  before 
returning  to  the  mainline. 

If  the  MFCS  is  closed  and  a redundant  CLOSE 
operation  is  attempted  then  control  branches 
directly  to  the  common  return  paragraph  "m". 
If  an  OPEN  operation  or  an  operation  that  can 
imply  opening  (most  record  level  operations) 
is  encountered  then  control  branches  to  the 
open  routine  paragraph  ”d”.  If  the 
operation  can  not  imply  opening  then  an  error 
is  raised;  a specific  error  code  is  posted  in 
the  HFCl  and  control  jumps  to  the  common 
return  - paragraph  ”m".  This  is  an  example 
of  the  general  method  RDBPAC  uses  when  it 
detects  an  error. 

If  the  HFCB  is  open  the  operation  code  is 
checked  for  validity.  Close  and  open  (which 
is  re-open  in  this  case)  operations  branch  to 
the  close  routine-?  paragraph  ”c".  Record 
operations  branch  to  paragraph  ”e".  Get 
operations  branch  to  paragraph  "h”.  Put  and 
Beput  operations  branch  to  paragraph  ”i".  An 
invalid  operation  cede  raises  an  error  and 
jumps  to  the  common  return  - paragraph  ”m”. 

c.  Close  Soutine 
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For  each  data  set  in  the  data  base  the  unlock 
subroutine  is  called  and  the  ASHCLOS  is 
called. 

Eor  a simple  close  operation  control  branches 
to  the  common  ireturn.  For  a close  erase 
operation,  ASMEHSE  is  called  either  for  the 
descriptor  data  set  or  for  the  ’’data”  data 
sets  and  control  branches  to  the  common 
return. 

Open  Boutine 

!rhe  TSS  userid  is  obtained  by  calling  ASHID* 
For  a re-open  operation  on  the  same  data  base 
with  the  same  security  password,  the 
following  descriptor  read-in  and  File  Control 
Block  (FCB)  initialization  _ steps  are 
bypassed. . For  an  open  operation  on  a 
descriptor  data  set,  a pointer  to  the 
hard-coded  descriptor  descriptor  table  in 
main  storage  is  posted  in  the  HFCB  and  the 
following  descriptor  read-in  step  is 
bypassed. 

To  read  in  the  descriptor  records,  ASHDCB, 
ASHFNDS,  and  ASMOPEN  are  called.  Then  for 
each  region  (describing  one  date  set)  ASMGETK 
is  called  to  read  the  file  descriptor  record 
and  ASM6ET  is  called  repeatedly  to  read  the 
field  descriptor  records.  A descriptor  for 
the  EECllN  field  is  bypassed  except  on  the 
first  data  set.  When  the  descriptor  for  the 
key  field  is  found,  it  is  stored  at  the  top 
of  the  DISC  table,  other  descriptors  are 
stored  sequentially  which  is  alphabetical  by 
field  name.  Superfield  descriptors  are 
reread  (by  calling  ASMGETK)  so  that  their 
component  fields  may  be  checked  (if  a 
component  has  failed  security  checking  then 
the  superfield  also  fails) . Finally  ASHCLOS 
is  called  to  close  the  descriptor  data  set. 

Next  for  each  data  set  a File  Control  Block 
(FCB)  is  allocated  and  a skeleton  Data 
Control  Block  is  copied  into  it  and  ASHFNDS 
is  called.  For  OOTPOT  or  UPDATE  mode  a null 
record  is  composed  in  the  FCB  by  finding  the 
primary  field  descriptors.  After  the  FCBs 
are  all  initialized,  then  file  and  field 
subscripts  (lUVFlCUfi, ASSOCCUB,SDBFLCUR,  and 
BEIFIDSS)  are  determined. 
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If  a non-descriptor  file  is  being  opened  for 
output  or  update  then  the  HNTNABIE  or  HN2NING 
switch  in  the  anchor  file  descriptor  record 
is  updated.  For  output  or  update,  any 
subfile  data  set  in  the  data  base  is  opened 
and  the  highest  id-key  in  use  is  found  by 
calling  ASMOPEU  and  ASHGETK.  If  the 
operation  was  an  explicit  open  then  control 
branches  to  the  coiBinon  return.  Otherwise  it 
was  an  implicit  open  and  control  proceeds  to 
the  record  routine, 

Eecord  Routine 

The  record-level  routine  is  used  for  WRITE, 
LOCATE,  BEAD  and  DHLOCK  operations.  The 
WRITE  operation  is  handled  separately  by 
calling  ASHPDTK  and  branching  to  the  common 
return. 

For  LOCATI  and  BEAD  operations,  the  element 
GET  cursors  are  reset  for  the  particular  data 
set  or  for  the  anchor  and  associate  data 
sets.  The  LOCATE  SOBETLE  operation  is 
handled  separately  at  this  point:  control 
branches  into  the  Put  routine  to  find  the 
anchor  or  associate  control  field  for  the 
subfile,  A suhrecord  id-key  is  determined 
from  the  highest  id-key  in  the  control  file 
or,  if  it  is  null,  from  the  highest  id  key 
previously  used  in  the  subfile,  A current 
subrecord  is  built  by  copying  the  null  record 
built  by  the  open  routine,  posting  the  new 
id-key  and  posting  the  parent  key  field  by 
copying  the  anchor  key  field.  Control 
branches  into  the  Put  routine  again  to  put 
the  new  element  into  the  control  field.  To 
tetter  ensure  data  base  integrity,  the  anchor 
or  associate  record  containing  the  control 
field  is  immediately  written  or  rewritten 
and  reread  by  calling  ASKPDTK  and  ASHGETK, 
If  the  control  field  is  on  an  associate  and 
the  anchor  record  was  newly  located  then  it 
is  written  and  reread  too. 

An  anchor  LOCATE  operation  is  handled 
separately  at  this  point;  control  branches  to 
the  Validate  key  routine  (described  with  and 
also-  used  by  the  READ  KEV  operation)  and  then 
an  attempt  is  made  to  read  the  new  key  using 
ASHGETK.  If  the  new  key  is  found,  the  record 
is  made  current  (just  as  if  a READ  KEI 
operation  had  been  requested)  and  an  error  is 
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raised.  Normally,  the  neu  key  will  not  be 
found  ana  a current  anchor  record  is  built  by 
coping  the  null  record  built  by  the  Open 
routine  (or,  for  a descriptor  data  set,  a 
hard-coded  null  file  or  field  descriptor 
record  is  copied)  and  the  new  key  valve  is 
posted  in  it. 

Spanned  index  reads  are  handled  separately  at 
this  point;  their  fundamental  objective  is  to 
make  the  last  record  of  a spanned  region 
current.  Por  read  INDEX  BACKNAEDS  either 
ASHSTLP  (if  the  old  suffix  was  0)  or  ASHSTLK 
(to  read  the  old  region  suffixO)  are  called 
and  the  ASHSTLP  is  called  to  position  at  the 
last  record  of  the  previous  region;  ?or  read 
INDEX  forwards  ASMGET  is  called  to  read  the 
first  record  of  the  next  region  and  then 
ASHSTIK  is  called  with  suffix  FF  to  position 
at  the  last  record  of  the  new  region.  For 
read  INDEX  KEY  the  validate  key  routine 
(described  later)  is  used  and  then  ASHSTLK  is 
called  with  suffix  FF  to  position  at  the  last 
record  of  the  new  region.  Then  for  all  types 
of  read  INDEX,  ASMGET  is  called  to  read  the 
last  record  of  the  new  region. 

Normal  (un-spanned)  reads  are  processed  as 
follows, . For  read  BACKWAEDS,  ASHSETL  is 
called  with  the  *P»  option  to  position  to  the 
previous  record.  For  read  forwards,  it  is 
unnecessary  to  do  any  file  positioning.  For 
read  PER  SUBFILE,  the  parent  key  value  is 
taken  from  the  current  subrecord  for  use 
without  validation.  For  read  by  KEY,  the 
Validate  key  routine  is  used.  The  Validate 
key  routine  (also  used  for  LOCATE  KEYFOEH) 
calls  the  generic  conversion  routine,  if 
specified  in  the  key  field  descriptor,  and 
then  calls  the  validation  routine,  if 
specified,  using  "CALL  CALL"  service  for  both 
purposes.  For  read  LIST,  the  appropriate  key 
value  is  taken  from  the  list  (next  forward, 
next  backward,  or  by  subscript)  for  use 
without  validation.  Then  for  all  non-locking 
direct  reads  (PER  SUBFILE,  by  KEY,  or  from 
LIST) , ASHSTLK  is  called  to  position  to  the 
desired  record.  Now  the  file  is  positioned 
for  all  reads  (except  direct  locking)  • and 
ASHGET  is  called  to  actually  read  the  desired 
record.  Then  if  the  record  is  to  be  locked 
and  for  direct  locking  reads,  ASHGETK  is 
called  to  reread  or  read  the  record  and  lock 
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it  for  exclusive  use.  Next,  for  INPUT  modes, 
any  record  level  security  checking  is  done; 
if  it  fails  anfl  it  was  a sequential  read 
<f orwards  or  backwards) , control  loops  back 
to  do  another  sequential  read  until  a record 
that  passes  security  or  end-of-file  is 
encountered*  If  record  security  fails  for  a 
direct  read,  a key--not-found  error  is  raised* 
Por  reading  a descriptor  data  set  only,  the 
region  is  compared  to  determine  if  the  read 
stayed  within  the  region  that  was  opened  and 
the  key  is  checked  to  determine  if  a file  or 
a field  descriptor  was  read  so  that  the 
pointer  to  the  appropriate  hard-coded 
descriptor  descriptor  table  can  be  posted  in 
the  HPCB  to  govern  subsequent  field  level 
operations.  If  an  anchor  record  was  read, 
then  all  subfiles  are  checked;  any  having  a 
current  subrecord  with  a different  parent  key 
to  the  new  anchor  key  are  marked  ”not 
current”.  If  a subfile  record  was  read,  then 
the  anchor  and  all  other  subfiles  are 

checked;  any  having  a current  (sub)  record 
with  a different  (parent)  key  to  the  new 
subrecord *s  parent  key  are  marked  ”not 

current”. 

BBPPIDT  Entry 

The  DBPELDT  (Post  ELDTAB)  entry  is  provided 
to  build  a Field  name  Table  by  reference  to 
EDBPAC’s  main  storage  descriptor  tables  built 
by  the  Open  routine.  This  entry  is  not 
supported  by  a DBPL/I  statement  a mainline 
program  must; 

i.  execute  a DBPL/I  OPEN  statement  or  a 

record  level  statement  implying 

opening. 

ii.  ”CALI  DBPELDT (mfcb) ; where  mfcb  is  the 
file  name  of  the  data  base  that  was 
opened. 

iii.  have  a »%  INCLUDE  LISHHAC(ELDTAB) ;« 
statement  to  copy  in  the  declaration  for- 
ELDTAB.  Use  of  this  entry  is  optional; 
BDEPAC  makes  no  use  of  ELDTAB, 

ELDTAB  Boutine 

ELDTAB  is  allocated  or  freed  and  reallocated 
with  its  size  adjusted  to  hold  the  number  of 


PAGE  95 


fieia  names  in  the  data  base*  SECLEH  and  the 
hey  field  name  are  posted, . - The  anchor 
descriptors  are  searched  to  find  anchor  field 
names  to  post  for  format  2,  The  anchor 
descriptors  are  searched  again  to  find 
associate  field  names  to  post  for  format  3* 
Each  sntfile’s  descriptors  are  searched  in 
tarn  to  post  subfile  field  names  for  format 
^1,  If  any  superfields  were  noticed  in  the 
anchor  or  associate  searches,  they  are  found 
again  and  their  components  analyzed  to 
determine  whether  to  post  the  superfield  in 
format  2 {all  components  from  anchor)  • or 
format  3 (one  or  more  associate  components 
but  no  subfile  components)  or  format  4 (one 
or  more  subfile  components) . 

Get  Eoutine 

The  Get  routine  is  used  for  all  GET 
operations  and  for  the  fflELD  and  #XBEf 
functions, 

Ehen  a field  name  has  been  passed  or  posted 
in  the  HfCB,  it  is  found  in  the  DESC  table 
to  determine  the  data  set  for  the  GETS 
otherwise,  the  first  data  set  (the  one 
specified  by  the  05EB  TITLE  cluse)  is 
implyed. 

If  that  data  set  does  not  have  a current 
record,  then  for  the  #XBEf  function  a zero  is 
returned.  If  it  is  the  anchor  data  set  and 
any  subfile  has  a current  record,  its  parent 
key  will  be  used  to  read  (using  ASMGETK) , 
The  anchor  record  whose  record  security  will 
be  checked;  if  it  fails,  a null  value- will  be 
returned  and  control  branches  to  the  common 
return  or,  for  #fIELD,  a zero  is  returned. 

The  GET  BECOID  operations  is  handled  by 
coping  the  record  from  the  PCB  to  the  user's 
string  and  branching  to  the  common  return. 

fox  the  GET  LIST  SET  Statement  (DBI)  and  GET 
lEDEX  LIST  SET  statement  (BB2)  the 
cross-reference  field  descriptor  is  found  and 
control  tranches  down  to  the  Get  field 
routine, 

for  "the  GET  KEI  SET,  GET  SUBfILE  KEY  SET  and 
GET  INDEX  KEY  statements  the  appropriate  key 
descriptor  is  found  and  control  branches  down 
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to  the  Get  Eield  routine, 

lor  the  #XEEF  function  the  cross-reference 
field  descriptor  is  found  and  control 
^branches  down  to  the  Get  Pield  routine. 

For  GET  FIELD,  #FIELD  and  GET  SDBFIIE  LIST 
SET  If  the  descriptor  found  previously  was  a 
dummy,  then  the  corresponding  real  descriptor 
must  he  found  in  an  associate  descriptor 
table.  For  GET  FIELD  and  #F1ELD  of-  a 
superfield,  .a  loop  is  initialized  to  take' 
each  component  field,  starting  with  the 
first,  find  its  read  descriptor  and  record 
{using  ASMOPEN  and  ASHGETK  for  an  associate 
record  if  necessary)  and  perforin  the  Get 
Field  routine  repeatedly  until  the  superfield 
has  heen  composed  or  its  count  determined. 

Get  Field  handles  a bit  field,  a fixed  length 
byte  field,  a simple  variable  field,  a fixed 
length  element  of  a multi-element  field  or  a 
variable  length  element  of  a multi-element 
field. 

GET  KEY  SET  operations  are  handled  separately 
after  the  fixed  length  key  has  been 
extracted.  If  necessary,  a list  segment  is 
allocated  and  chained  and  initialized. 

For  -the  SUBFILE  option  the  subfile  id-key 
field  name  is  found  in  the  subfile  descriptor 
table.  For  an  index  option,  if  the  index  is 
spanned  and  the  last  suffix  is  greater  than 
zero,  the  first  record  in  the  region  is  read 
using  ASEGETK  and  control  branches  back  to 
the  Get  Field  routine,  A list  segment  is 
allocated,  with  its  size  governed  by  the 
field’s  length,  and  chained  and  initialized 
and  posted  with  the  whole  multi -element  field 
value.  For  a spanned  index,  if  the  suffix  is 
less  than  the  last  in  the  region,  then  the 
next  index  record  is  read  using  ASHGET  and 
control  branches  back  to  the  Get  Field 
routine;  this  repeats  until  the  whole  region 
has  been  copied  into  list  segments  and  -the 
data  set  is  positioned  at  the  last  record  of 
the  region  again. 

The  #FIELD  function  is  handled  for  the  null 
and  real  value  cases  of  all  five  types  of 
direct  fields  and  for  the  case  of  an  empty 
associate  data  set  or  an  absent  associate 
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record.  Superfields  are  handled  by 

effectively  evaluating  #FIELD  for  each 

component  to  determine  the  net  count.  The 
#XEEF  function  for  a spanned  index  calculates 
the  number  of  cross-references  on  records 
preceding'  the  last  in  the  region  by  assuming 
full  maximum  length  records  and  adds  the 
number  of  cross-references  on  the  last 
record.  The  #TIELD  and  #XBEF  functions  are 
thus  complete  and  return  their  function  value 
directly  (without  branching  to  the  common 
return) . 

The  GET  INTO  operations  are  handled  for  the 
null  and  real  value  cases  of  all  five  types 
of  direct  fields  and  for  the  case  of  an  empty 
associate  data  set  or  an  absent  associate 
record.  Superfields  are  handled  by  looping 
back  to  get  each  component  field  and 

concatenating  them  together. 

i.  Put  Eoutine 

The  field  name  passed  in  the  HFCB  is  found  in 
the  DESC  table  to  determine  the  data  set 
implicated.  If  it  is  an  associate  data  set, 
it  is  opened,  if  necessary,  by  calling  ASOPEN 
and  read,  if  necessary,  by  calling  ASHGETK 
and  if  the  record  is  absent  a current 
associate  record  is  built  by  copying  the  null 
record  built  by  the  open  routine  and  the 
anchor  key  value  is  copied  into  it.  If  an 
anchor  key  or  a subfile  id-key  is  being  EEPUT 
to  null,  then  control  branches  to  the  Delete 
routine  described  in  paragraph  "j"  below. 

For  a fixed  length  field  or  element,  the  new- 
value  is  justified  right  or  left  depending  on 
the  KOMAIIGN  switch  in  the  field  descriptor. 
For  a variable  length  or  multi-element  field, 
the  field  length  and  record  length  (SECLEN. 
field)  are  adjusted  as  necessary.  If  the 
field  is  indexed  and  had  a non-null  value, 
then  the  Delete  XEEF  subroutine  (described 
in  paragraph  ”1”  below)  is  called.  If  the 
new  value  is  non-null  and  the  field  is 
indexed,  then  the  XEEF  subroutine  (described 
in  paragraph  ”k"  below)  is  called. 

j.  Delete  Eoutine 

Nulling  a subfile  id-key  indicates  that  a 
subrecord  is  to  be  deleted.  The  subfile 
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control  field  descriptor  is  found  and  if  it 
is  on  an  associate,  the  associate  data  set  is 
opened,  if  necessary,  by  calling  fiSOPEN  and 
read,  if  necessary,  by  calling  fi.SHGET-K,  The 
control  field  element  is  found  and  excised 
and  the  field  length  and  RECIEN  arej 
decremented.  Then  the  subfile  descriptors ^ 
are  searched;  for  all  indexed  fields,  the’ 
Delete  XREF  subroutine  (described  in 
paragraph  ”1”  beloi?)  is  called  for  each, 
element  value.  Finally  the  subrecord  is, 
deleted  by  calling  ASKDELB,  ‘ 

Hulling  an  anchor  key  indicates  that  an 
anchor  record  and  its  associated  and; 
subordinate  records  are  to  be  deleted.  The' 
anchor  descriptors  are  searched  for  subfile 
control  fields  and  for  indexed  anchor  or 
associated  fields.  If  a control  or  indexed 
field  is  found  on  an  associate  data  set,  it 
is  opened,  if  necessary,  by  calling  ASHOPEN 
and  read,  if  necessary,  by  calling  ASMGETK, 
For  each  control  field,  the  subfile  is 
opened,  if  necessary,  by  calling  ASHOPEH  and' 
each  element  is  used  to  read  a subrecord 
using  ASMGETK.  The  subfile  descriptors  are 
searched  for  every  subrecord;  for  all  indexed' 
fields,  the  Delete  XREP  subroutine  is  called. 
Each  subrecord  is  deleted  by  calling  ASMDELB,' 
During  the  anchor  descriptor  search,  when  an 
indexed  anchor  or  associate  field  is  found, 
the  Delete  XEEF  subroutine  is  called. 

XBEF  Subroutine 

The  XEEF  subroutine  is’  called  from  the  Put 
routine  when  a ncn-null  value  is  PUT  or  BEPOT 
to  an  indexed  field.  The  inverted  index  data 
set  is  opened,  if  necessary,  by  calling 
ASMOPEH,  Then  an  index  read  is  attempted 
using  ASMGETK  (with  a suffix  of  zero  if  it  isj 
spanned).  If  the  record  is  not  found,  then' 
the  null  record  built  by  the  Open  routine  is 
copied,  the  cross-reference  and  the  indexed 
value  are  copied  in,  it  is  written  by  calling 
ASHPOTK  and  control  returns  to  the  calling 
program. 

If  an  index  record  is  found,  then  its  highest 
(rightmost)  cross-reference  value  is  compared 
with  the  new  cross-reference.  If  the  new 
reference  is  lower,  then  the  insertion  point 
is  found  by  a binary  search  and  the  new 
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reference  inserted:;  other'aise  the  new, 
reference  is  appended.  If  the  index  is  not 
spanned  or  if  the  region  only  needs  one 
record,  the  cross-reference  field  length  and, 
PECLIN  are  incremented,  the  index  record  is 
rewritten  using  JSHPOTK  and  control  returns 
to  the  calling  program* 

In  a spanned  index  region  ifhen  the  zero 
suffix  record  is  full,  if  its  last  reference 
is  less  than  or  egual  to  the  new  reference 
then  it  is  released  by  calling  ASMEEL; 
otherwise  the  insertion  point  is  found  by  a 
binary  search,  the  new  reference  is  inserted, 
the  last  reference  overflows  to  become  the 
new  reference  to  be  propagated  forward,  and 
the  record  is  rewritten  using  ASHPI3TK.  The 
suffix  is  incremented  and  control  loops  back 
to  attempt  a read  of  the  next  record  of  the. 
region,  Ihis  continues  as  long  as  full 

records  are  found,  finally  a short  record  is 
found  to  append  to  or  a fresh  record-  is 
created  and  the  process  is  completed  like  a 
non-spanned  case  and  control  returns  to  the 
calling  program. 

Delete  XEEF  Subroutine 

Ihe  Delete  XEEF  subroutine  is  called-  from  the 
Put  routine  when  an  indexed  field  that  had  a 
non-null  value  is  being  EEPOT,  It  is  also' 
called  exhaustively  by  the  Delete  routine  for 
indexed  fields.  The  inverted  index  data  set 
is  opened,  if  necessary,  by  calling  ASMOPEN. 
If  the  index  is  spanned,  the  last  suffix  of 
the  region  is  determined  by  calling  ASHSTLK 
with  a suffix  of  and  fiSEGET.  Whether  or 

not  the  index  is  spanned,  ASHGETK  is  called;  ’ 
to  read  the  index  record  (with  the  highest 
suffix  if  it  is  spanned) . If  the  index  is 
not  spanned  or  if  the  region  only  has  one 
record,  then  the  cross  reference  is  found  by 
a binary  search  and  excised,  the  ■ 
cross-reference  field  length  and  BECLEN  are" 
decremented , the  index  record  is  rewritten 
using  ASHPDTK  and  control  returns  to  the 
calling  program.  In  the  exceptional  case  of 
the  index  record  only  having  the  one 
cross-reference,  it  is  -deleted  using  ASHDELB 
and  control  re-turns  to  the  calling  program. 

In  a spanned  index  region  having  more  than' 
one  record,  the  lowest  (leftmost) 
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cross-reference  value  is  examined  before  the 
binary  search.  If  it  is  greater  than  the 
cross-reference  to  be,  deleted,  then  the  whole! 
cross-reference  falls  off  to  be  rolled' 
backward  in  the  region.  The  record  is  then 
rewritten  (with  the  field  length  and  RECLES 
decremented  if  necessary)  using  A'SHPDTK  or 
deleted  using  ASHDEIB,  Then  the  previous 
record  is  read  using  ASMGETK  with  the  next 
lower  suffix  and  the  lowest  cross-reference 
examined.  This  process  repeats  rolling  one 
cross-reference  backward  in  the  region  until 
the  record  is  found  with  a lowest 
cross-reference  less  than  or  egual  to  the  one 
to  be  deleted.  The  cross-reference  is  found 
by  a binary  search  and  excised,  the  rolled 
cross-reference  from  the  record  just 
processed  is  posted  at  the  right  end,  the 
record  is  rewritten  using  ASHPUTK  and  control 
returns  to  the  calling  program.  If  the  cross 
reference  is  not  found  !cn  the  record,  it 
belongs  on  then  the  record  is  released  using 
ASMREL  and  in  the  simple  case  control  returns 
to  the  calling  program.  However,  if  rolling 
hack  had  been  started  in  a spanned  region, 
one  cross-reference  is  still  in  limbo,  so 
control  branches  into  the  XE-EF  subroutine 
which  will  roll  one  cross-reference  forward 
from  that  point  to  reconstruct  the  region 
before  returning  to  the  calling-program;  this 
should  he  an  extremely  infrequent 
occurrence. 

Return 

The  common  Return  is  used  by  all  routines. 
The  only  exception  is  that  when  the  #EIELI) 
or  #XREI  functions  complete  successfully  they 
return  directly, 

Bhen  an  error  has  been  detected,  an  error 
code  is  posted  in  the  HECB,  The  address  of 
the  HFCB  is  posted  in  DBEFCBP  to  assist  any 
mainline  having  multiple  HFCBs,  If  the 
mainline  has  a current  DBPL/I  OK  ERRORFILE  GO 
TO  action,  then  RETRKPT  is  called  to  post 
HFCB,OKEETUBK  and  RDEPAC  is  left  by  branching 
to  the  mainline  label  in  HFCB. ERROR, ROUTINE, 
Otherwise  RBBPAC  is  left  by  signalling  the 
PI/I  ERROR  condition  which,  unless  the 
mainline  catches  it,  will  terminate  the 
mainline  program. 
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Hormadly,  RBBPAC  is  leit  by  a simple  SETDEN 
sta-teroen-t  and  control  returns  to  the  mainline 
that  called. 

CODIHG  SPECIEICATIONS 

1,  Source  language 

SDBPAC  is  written  in  PL/I,  The  DB  preprocessor 
and  BBPl/I  are  not  used  in  SDBPAC,  Various 
Assembler  language  subroutines  are  used  as 
mentioned  in  the  Processing  Sequirements 
Narrative, 

2,  Suggestions  and  Techniques 

Nhen  a desired  field  descriptor  has  been  found  by 
subscript  in  the  tables,  its  address  is  held  in  a 
pointer  variable  and  based  structure  references 
ate  used  to  avoid  frequent  re-evaluation  of  the 
subscript.  Similar  techniques  are  used  whenever 
possible. 

Binary  search  techniques  are  used  to  maintain  the 
cross-reference  lists  in  inverted . index  records  in 
ascending  sequence.  ‘ 

The  facilities  available  in  the  RDETSSIO  module 
are  used  to  the  best  possible  advantage  with  the 
TSS  operating  system  VISAM  access  method. 

The  SDBPAC  module  is  designed  and  implemented  to 
be  reentrant  under  multi-programming;'  automatic, 
controlled  and  based  storage  are  used 
appropriately.  One  hnown  exception  is  that  • the  . 
main  storage  descriptor  descriptor  tables  are 
static  for  efficiency;  if  two  or  more  users 
attempt  to  access  the  same  descriptor  data  set 
region  concurrently  they  may  encounter 
interference  on  the  multi-element  field  cursors 
(only  ESECTYCD,  NAMEFLD  and  SECDSITY  fields  are 
affected) , 
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TOPIC  B. 3 - EXECDTIVE  ASSEMBLER  PROGRAMS 


A.  MODULE  NAME 

Executive  Assembler  Program 
Program-ID  - RDETSSIO 
Module-ID  - HDBTSSIO 

B.  AMALIST 

Phillip  D.  Pritchard 
Keoterics,  -Inc, 

C.  MODULE  EUHCTIOU 

This  program  works  in  con jtmction  with  the  Data  Base 
Executive  Program  (BDBPAC)  -and  provides  the  assembler 
language  macros  required  to  ^handle  the  input,  output 
and  updating  of  VISAH  files,  as  well  as  the  handling  of 
error  conditions. 

These  VISAS  files  are  the  files  of  a data  base  and  the 
Data  Base  Executive  will  call  the  Executive  Assembler 
Program  when  it  needs  an  I/O  operation  performed, 

D.  DATA  REQUIEEHESTS 

1.  I/O  Block  Diagram 
See  Eigure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Rot  Applicable 

b.  , Punched  Card  Input  Files 

Not  Applicable 

c.  Input  Files 

All  of  the  files  which  mak«  up  a uara  oase 
could  conceivably  be  input,  including 
descriptor  files.  The  only  real  restriction 
is  that  the  files  be  VISAH, 

d*  On-line  Terminal  Entries 

Not  Applicable 
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3,  Output  Bata  Sets 
a.  Output  Files 

Same  as  input  files. 
hi  On-line  Terminal  Displays 
Not  Applicable 

c.  Formatted  Print-outs 
Sot  Applicable 

d.  Puncfied  Card  Output  Files 
Not  Applicable 

4.  Eeference  Tables 
Not  Applicable 

PROCESSING  RIQOIBEKENTS 

1. -  Top  -level  Flowchart 

See  Figure  2 

2.  Narrative 

This  program  is  designed  to  handle  the  input  and 
output  functions  for  the  Data  Base  Executive 
(SDBPAC) . It  deals  strictly  with  VISAH  files. 

The  program  is  divided  into  many  routines,  and 
each  of  these  routines  has  a unique  function 
(Illustrated  in  Table  1-) « The  Data  Ease  Executive 
(BDBPAC)  calls  these  routines  individually  to 
perform  the  various  functions  which  are  required. 
Associated  with  each  of  these  calls  is  the 
passing  of  the  required  parameters. 

The  abilities  of  these  assembler  routines  are 
comprehensive  enough  to  handle  any  situation  which 
might  arise  in  the  Data  Base  Executive.  This 
includes  the  abilities  tot  open  fiies  for  input, 
output,  or  update;  read  the  file  sequentially, 
read  the  file  by  hey,  exclusively  or 
non-exclusively;  position  the  file  to  the 
beginning,  the  end,  the  previous  record  or  the 
next  record;  and  close  the  file.  For  example,  if 
the  Bata  Base  Executive  were  required  to  open  a 
data  base  in  the  update  mode  and  process  records. 
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the  sequence  of  calls  nould  be  as  follows; 

CALI  ASHDCB  tparameters) 

. establish  the  files  DCB  (data 

control  bloch) . 

CALL  ASHfNDS  (parameters) 

linh  the  DCB  with  the  JECB  (job 
file  control  block) • 

CALI  ASKOPEN  (parameters) 
open  the  file. 

CALL  ASHGETK  (parameters) 

read  a record  by  key, 

CALL  ASHIUTK  (parameters) 

rewrite  the  record. 

CALL  ASKCLOS  (parameters) 
close  the  file. 

The  Executive  Assembler  Eoutines  (RDBTSSIO)  is 
called  from  the  Data  Base  Executive  (BDBPAC) . If 
no  errors  are  detected  by  the  assembler  routines, 
the  error  switch  (one  of  the  parameters)  is  set 
equal  to  zero  upon  return- to  EDBPAC  and  the  return 
is  to  the  specified  'Good*  return  address • (one  of 
the  parameters) . If  an  error  is  detected  by  the 
assembler  routines,  the  error  switch  is  set  with 
the  proper  error  code  and  the  return  is  to  the 
next  sequential  instruction  in  RDBPAC.  The  error 
codes  will  have  the  following  values  when  an  error 
occurs  in  ASHOPEH,  ASHPOTK,  ASMGETK,  ASHGET, 
ASHPDT,  ASHSETL,  ISKESTL,  ASHREL,  ASHCLOS,  ASMDELR 
or  ASKSTLK; 

a,  04  - keys  equal  (sequence  error) 

b,  08  - key  not  found 

c,  12  - key  out  of  sequence 

d,  15  - keys  do  not  coincide 

e,  20  - keys  coincide 

f,  24  - invalid  retrieval  address 

g,  28  - invalid  record  length 

h,  31  - position  past  end  of  data  set 

i,  36  - position  before  start  of  data  set 

j,  . 40  - exceed  maximum  number  of  overflew  pages 

k,  44  - exceed  maximum  size  of  stored  data  set 

The  assembler  routines  will  add  100  to  all  of  the 
above  error  codes  prior  to  returning  to  the  Data 
Base  Executive  (RDBPAC) . The  end  of  data  exit 
sets  the  error  switch  to  99,  The  error  switch  is 
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a fixed  binary  half-word. 

The  first  parameter  is  always  the  DCS  address  <DCB 
means  Data  Control  Block) , The  second  parameter 
is  the  record  area,  except  for: 

a.  The  open  (ASMOPEN)  - in  this  instance,,  it  is 
a one  byte  function  code  - 

I = input 
0 = output 
D = update 

b.  The  close  (ASMCLOS) 

ESETI  fASHESTl) 

STLK  (ASJ3STLK) 

EEl  (ASHEEl)  - in  these  instances,  it 
is  a one  byte  dummy  character  (no 
meaning, ) 

c«  The  DEIBEC  (ASHDEIE)  - in  this  instance,  it 
is  the  key, 

d.  The  SETL  (ASHSETL)  - in  this  instance,  it  is 
a one  byte  function  code  — 

B = beginning 
E = end 
M = next 
P = previous 

The  third  parameter  indicates  the  routine  to  which 
return  is  made  if  there  are  no  errors, 

NOTE;  The  error  switch  parameter  for  the 
following  routines  must  be  preset, 

a,  ASHGETK  - 01  if  KY (Bead  by  key) 

00  if  KX  (Bead  by  key  exclusive) 

b,  ASHPOTK  - 01  if  ET  (Write) 

00  if  KS  (Bewrite) 

The  routines  and  their  functions  are  as  follows; 

a,  ASHENDS;  This  routine  obtains  the  location 
of  the  JECB  corresponding  to  a given  data 
set  name.  If  the  data  set  name  specified  is 
not  in  the  task  definition  table  (DDEF*ed) 
but  is  in  the  catalog,  the  JECB  is  created. 

If  the  data  set  name  specified  is  in  the  task 
definition  table  (DDEFed) , the  JECB  is 
already  in  existance.  If  the  data  set  name 
is  neither  DDEEed  nor  cataloged  and  the  key 


PAGE  108 


length  is  passed  as  a parameter  in  the  error 
swiich,  the  tile  is  PBEFed  and  the  JFCB  is 
created. 

The  DDNAHE  used  is  posted  from  the  JPCB  to 
the  DCB,  and  the  owner-lB  is  posted  from  the 
JTCB  to  the  user’s  area. 

The  parameters  required  for  successful 
execution  of  the  FINDBS  are  as  follows-; 

1.  The  DS  name  <35  characters) 

2.  The  DCB  address 

3.  The  owner’s  ID 

t|.  The  error  switch  (key  length) 

b.  iSMCAT;  This  routine  does  a standard  catalog 
of  the  string  passed  as  the  first  parameter. 
The  string  has  the  standard  CAT  macro  format. 
The  parameters  are  as  follows; 

•1 . The  catalog  parameter 

2.  The  return  code 

c.  ASHPE;  This  routine  tries  to  do  a macro 
print  on  the  string  that  is  passed  as  the 
first  parameter.  It  has  the  format  of  a 
standard  PBINT  macro  parameter.  The 
parameters  are  as  follows; 

1.  The  PBIIST  parameter 

2.  The  return  code 

d.  ASHEBSE;  This  routine  erases  the 

direct-access  storage  for  a data  set.  In 
addition,  it  will  remove  the  entry  for  a 
catalogued  data  set  from  the  catalog.  The 
DSHAHE  passed  is  padded  with  blanks  to  35 
characters.  If  a stored  data  set  is  opened 
by  many  users  concurrently,  a particular  user 
cannot  erase  that  data  set  until  every  other 
sharer  actively  using  that  data  set  Issues  a 
close. 

Once  a user  is  the  only  currently  active  task 
using  the  data  set,  he  may  erase  it 
regardless  of  whether  he  has  closed  it  or 
not. 

The  parameters  required  are  the  DSHAHE  and 
the  error  switch, 

KOTE;  lor  both  ASMTNDS  and  ASHEESE,  the 
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error  switch  upon  return  to  the  Data 
Base  Executive  is  equal  to  zero  only  if 
no  error  occurred. 

ASH0PE8:  This  routine  connects  the  data  set 

to  the  system  by  completing  the  DCB 
(containing  the  attributes) , indicates  the 
manner  in  which  the  data  set  is  to  be 
processed  and  positions  the  data  set  for 
processing.  The  address  of  the  SYBAB  routine 
(SYNADETH)  and  the  address  of  the  EODAD 
routine  (EODADETH)  are  posted  to  the  DCB. 
The  address  of  the  save  area  is  also  posted 
to  the  DCB. 

The  parameters  are  as  follows: 

1.  The  DCB  address 

2.  The  function  code 

3.  The  *Gocd*  return  address 

4.  The  error  switch 

ASHDDTK:  This  routine  moves  a selected 

record  from  a user  specified  area  to  an 
output  buffer.  The  system  then  includes  the 
record  in  the  output  data  set  by  key.  This 
operates  in  one  of  two  modes:  Bewrite  (KS) 

or  write  (KT) . Write  releases  any  page  level 
interlocks  set  for  the  data  set.  The 
parameters  are  as  follows: 

1.  The  DCB  address 

2.  The  record  area  (address) 

3.  The  *Good*  return  address 

4.  The  error  switch  (preset: 

0 means  Bewrite  (KS) t 

1 means  Write  (KT) ) . 

5.  The  key  (address) 

ASHGETK:  This  routine  obtains  a selected 

logical  records  from  an  input  data  set  and 
moves  it  to  a user  specified  area.  There  ate 
two  modes,  read  with  interlock  (KX)  and  read 
with  no  interlock  (KY) , both  by  key.  The 
parameters  are  as  follows: 

1.  The  DCB  address 

2.  The  record  area  (address) 

3.  The  'Good*  return  address 

4.  The  error  switch  (Preset;  01  means  read 

•with  interlock  (KX)  , 00  means  read  with 
no  interlock  (KY) ) . 

The  key  (address) 
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h.  -ASHGET:  This  rouhiae  obtains  the  next 

sequential  record  and  moves  it  from  an  input 
buffer  to  a user  specified  area.  The 
parameters  are  as  follows; 

1»  The  DCB  address 

2.  The  record  area 

3.  The  *Gocd*  return  address 

4.  The  error  switch 

i«  ASHPUT:  This  routine  has  the  same  parameters 

as  the  ASHGET  routine.  However,  instead  of 
reading  a record,  it  writes  a record. 

j.  , ASMSTLK,  ASflSETl;  These  routines  position  a 

data  set.  The  parameters  for  both  routines 
are  as  follows; 

1.  The  DCB  address 

2.  The  code  ; K (by  hey) 

B (beginning) 

E (end) 

N (next) 

P (previous) 

NOTE;  the  *P'  actually  does  two 
SETl  *P*s  in  order  to  allow  for 
reading  the  file  backward, 

3.  The  ’Good*  return  address 

4.  The  error  switch 

5.  The  key  (address,  for  ASHSTIK  only) 

k,  . ASHSTLP;  This  routine  has  the  same 

parameters  as  the  ASHSTIK  and  ASHSETL 
routines.  It  does  one  SETl  *P*. 

l.  ASHESTL;  This  routine  releases  a page  level 
interlock  imposed  by  another  macro. 

The  parameters  are  as  follows; 

1,  The  DCB  address 

2,  A dummy  character 

3,  The  ’Good*  return  address 

4,  The  error  switch 

m,  ASHDELE;  This  routine  deletes  a record  from 
a 71SAH  file.  The  parameters  are  as 
follows; 

1,  The  DCB  address 

2,  The  key 

3,  The  ’Good’  return  address 

4,  The  error  switch 
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n,  aSMREL;  This  routine  makes  the  record 
available  to  other  users; 

The  parameters  are  -the  same  as  in  the  ASHESTL 
routine, 

o,  ASMCIOS:  This  routine  closes  the  file 

(VISAS) , 

p,  ASMDB;  This  routine  does  a general  purpose 
DDEF  after  trying  to  release  the  »UNIQUE» 
DDHAHE  it  creates.  It  then  passes  the  DDMME 
to  the  calling  program.  The  parameters  are 
as  follows: 

1.  The  DDEE  parameter  string 

2.  The  returned  DDHAME 

3.  The  return  code 

The  first  parameter  is  the  DDE?  information, 
identical  to  the  parameter  string  for  the 
DDE?  macro,  less  the  leading  *DDNAHE-*, 

The  second  parameter  like  the  first  is  a 
varying  character  string.  It  is  the  variable 
to  nhich  the  DDNAHE  is  returned.  The  third 

parameter  is  the  return  code  for  the  DDE?, 

g.  STNADETS,  ECDADITH:  When  an  end  Of  file  or 

some  error  is  detected  during  any  of  the 
routines  in  this  program,  these  routines  set 
the  proper  error  code  in  the  error  switch  and 
return  control  to  the  I)ata  Base  Executive  for 
appropriate  action, 

r,  ^ GETSECSD,  OTHGET;  When  a read  by  key, 
non-exclusive,  is  executed  and  an  error  is 
detected,  they  will  function  as  follows; 

When  the  ASEGETK  is  called  to  read 
non-ex clu si vely  and  the  record  is  not  found 
(EBEOB  X*08»)  then  a SETLK  to  the  net-found 
key  is  performed.  This  action  positions  the 
data  set  to;  The  last  record  if  the  key  is 
beyond  the  end  of  the  data  set,  to  the  next 
lowest  key  if  the  key  is  in  the  central 
portion  of  the  data  set,  and  to  the  first 
record  if  the  key  is  prior  to  the  beginning 
of  the  data  set.  The  SETLK  returns  to  the 
SYDAD  routine.  At  this  point,  the  record 
indicated  is  read.  An  error  code  of  X*108* 
is  returned  to  the  calling  module  (HDBPAC) , 
but  in  fact,  the  record  indicated  is 
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current, 

ASMDCB:  This  routine  tahes  the  DCB  created 

in  this  program  and  moves  it  to  the  user’s 
specified  area.  The  only  parameter  is  the 
user  specified  area  (address) • 

ASBIDi:  This  routine  determines  the  user  - ID 

(ISS  ^ ID)  of  the  task  and  places  it  in  the 
user  specified  area.  The  only  parameter 
passed  is  the  address  of  the  user  specified 
area. 

ASHEELSt  This  routine  is  used  to  release  the  ’ 
JECB  created  by  the  BDEEing  of  a particular 
file.  The  only  parameter  passed  is  the 
BDHAHE  associated  with  the  DDEP,  Any  errors 
that  occur  axe  Ignored, 

CAIL;  This  routine  allows  a PL/I  program  to 
call  an  external  routine  by  specifying  its 
name  at  execution  time.  Any  parameters  other 
than  the  called  routine  name,  are  passed  on 
to  the  called  routine  for  interpretation. 
The  name  specified  must  conform  to  the  name 
construction  standards  of  TSS/360. 

EETENPT;  This  routine  is  used  by  the  Data 
Base  Executive  error  routine.  It  posts  the 
double  word  in  the  HFCB  so  that  the  user  (of 
DBPAC)  can  return  to  the  next  sequential, 
instruction  in  his  program  after  the 
occurrence  of  an  error.  The  first  word  is 
the  invocation  count;  the  second  word  is  the 
address. 

ASHllODE;  This  routine  is  used  to  determine 
if  the  maintenance  task  is  running  in  a batch 
mode.  It  returns  a *C*  if  running 
conversationally;  or  it  returns  a 'B*  if 
not, 

IBDCHEK:  This  routine  is  used  to  validate 

the  construction  of  an  external  name.  The 
rules  used  are: 

1.  the  name  roust  begin  with  an  alphabetic 
character  (including  t,  $,  3) , 

2.  the  name  must  be  eight  characters  or 
less, 

3.  the  second  and  subsequent  characters  of 
the  name  must  be  alphanumeric  (including 
#,  $,  3,  ?)  . 
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!The  parameters  passed  are  the  ranie  and  the 
name  length  {in  the  event  that  the  user 
wishes  to  restrict  it  to  less  than  eight-)  • - 
If  the  name  is  invalid,  the  length  paramter 
will  he  set  to  one,  as  an  error  indicator, 
otherwise  it  will  be  set  to  zero, 

z,  ASJ3XTE,  aSHPASS,  ASUMOSI:  These  entry  points 

simply  transfer  control  to  the  MTT  monitor 
to  maintain  linkage  conventions, 

CODING  SPECIPICATIONS 

-1,  Source  language 

Unlike  most  other  modules  for  the  NASIS  system, 
the  Executive  assembler  program  (EDBTSSIO)  is 
written  entirely  in  Assembly  language, , 

2,  Suggestions  and  Technigues 

a.  Special  attention  is  paid  to  the  linkage 
conventions  of  the  current  PI/I  compiler, 

b.  The  Data  Base  Executive,  by  design,  is  the 
primary  user  of  this  program.  However,  the 
program  is  written  so  that  programs  other 
than  the  Data  Ease  Executive  can  use  it. 
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PARAMETER 

NUMBER 

REGISTER 

NUMBER 

PARAMETER 

1 

■ 2 

DCB  ADDRESS 

2 

3 

RECORD  AREA 
FUNCTION 
DUMMY 
KEY 

3 

4 

■GOOD’  RETURN 

4 

5 

ERROR  SWITCH 

5 

6 

KEY 

TABLE  I.  - PARAi'^lETERS. 
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TOPIC  B. 4 - DATA  BASE  EXECUTIVE  CONVEESION  AND  EEFOBBATTIHG 
BOUTIMES 


A.  HODUIE  NA0E 

Stanflara  Conversion  an3  Be formatting  routines  for  the 
Descriptor  Editor  and  the  Data 
Base  Executive. 

Program~ID  - RDBBXITS 
Hodule-ID  - DBEXITS 

Entry  Points  *•  See  Table  1. 

B.  ASAiyST 

Garth  B.  Uyman 
Neoterics/  Inc, 

C.  HODULE  EUNCTIOB 

This  module  provides  31  standard  general  field 
conversion  and  reformatting  routines.  They  are  called 
by  the  Data  Base  Executive  field  processing  routines 
(PUT,  GET.  and  5EPUT)  if  they  are  specified  in  the 
field  descriptor  record.  The  routines  are  written 
according  to  the  DBPAC  Exit  Boutines  User’s  Guide 
(Section  8.  Topic  B.1)  and  may  be  used  for  user’s 
database  fields,  if  desired, 

D.  DATA  BEQUIFEHEUTS 

1,  I/O  Block  Diagram 
Not  Applicable 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  . Input  Files 

Net  Applicable 

3,  Output  Data  Sets 
a.  Output  Files 
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Mot  ApplicablG 

b.  On-line  Terminal  Displays 
Mot  Applicable 
c*  Tormatted  Print-outs 
Mot  Applicable 
4,  fieference  Tables 
Hot  Applicable 

E, . PROCESSING  REQDISEBIMTS 
1*  Top  Level  Elouchart 
Hot  Applicable 
2.  narrative 

Tbe  conversion  routines  (DBCVT ) are  for  use 

during  PUT  or  REPOT  field  processing.  They  all 
accept  a varying  length  character  string  argument 
and  all  allow  the  value  to  have  leading  and 
trailing  blanks.  They  check  the  argument  value 
according  to  the  Notes  in  Table  1.  If  the 
argument  value  is  invalid,  they  return  with  the 
BAD  parameter  left  set.  Otherwise  they  copy  the 
value  or  convert  it  to  the  internal  form  and 
length  shown  in  Table  1,  reset  the  BAD  parameter 
switch  and  return. 

The  reformatting  routines  <DBEMT ) are  for  use 

during  GET  field  processing.  They  all  accept  a 
varying  length  character  string  argument  (from  the 
dataplex).  If  the  argument  length  is  not  as  shown 
under  ’’Internal  bytes”  in  Table  1,  then  the 
routine  is  being  misused  and  the  value  ”BAD.  HEX=” 
is  generated  followed  by  the  hexadecimal  expansion 
of  up  to  eight  bytes  of  the  argument.  Normally 
the  internal  form  of  the  value  is  reformatted  to 
the  external  form  and  control  is  returned.  These 
routines  all  produce  exact  length  output  (i.e. 
without  leading  or  trailing  blanks) . 

E.  CODING  SPECIEICA TICKS 
1.  Source  language 

Pl/I  with  no  DBPl/I  statements. 


Suggestions  and  Technigues 
Not  Applicable 


TABLE  I 


CONVERSION 

ROUTINE 

NOTES 

PURPOSE 

INTERNAL 

BYTES 

REFORMATTING 

ROUTINE 

DBCVTS 

1 

Scientific  (long  float) 

8" 

DEFICITS 

DBCVTSS 

1 

Short  Scientific  (short  float) 

4 

DBF^^^SS 

DBCVTLN 

1 

Long  Numeric  (fullword  binary) 

4 

DBFMTLN 

DBCVRSD 

1 

Scaled  Decimal 

5 

DBFMTSD 

DBCVTSN 

1 

Short  Numeric  (halfword  binary) 

2 

DBFMTSN 

DBCVTBN 

1 

Byte  Numeric  (quartenrord  binary) 

1 

DBFMTBN 

DBCVTRL 

1,2 

RECLEN 

4 

DBFMTRL 

DBCVTID 

1 

subfile  ID  key 

3 

DBFMTID 

DBCVTFT 

3 

header  descriptor  FILETYPE 

1 

DBFMTFT 

DBCVTFV 

4 

field  descriptor  Fixed  or  Varying 

35 

DBFMTFV 

DBCVTOO 

5 

Off  or  On 

% 

DBFMTOO 

DBCVTRS 

6 

header  descriptor  RSECTYCD 

9 . 

DBFMTRS 

DBCVTNF 

7 

super-field  descriptor  NAMEFLD 

9 

DBFMTNF 

DBCVTEK 

8 

External  Name 

1-8 

(DBFMTSB) 

DBCVTSB 

Strip  Blanks 

variable 

DBFHTSB 

DBCVTHX 

9 

Hexadecimal 

variable 

DBFMTHX 

1. 

Arethmetic  conversion  and  size  checking. 

2. 

Value  between  4 and  4000. 

3. 

Valid  values  are:  anchor,  1:  associate. 

2; 

subfile,  3;- 

index,  4. 

4. 

Valid  values  are:  fixed,  f , 0;  varying. 

V, 

1. 

■5. 

Valid  values  are:  off,  no,  n,  false,  f. 

0; 

on,  yes,  y. 

true,  t,  1. 

6. 

Has  the  form:  nasis— id  hexmask. 

7. 

Has  the  form:  <external|elinternalli>  comoonent-fleld-uamp. 

8 • 

Fxrst  non-blank  alphabetic;  other  characters 

alphaniimeric . 

9. 

Valid  non-blank  characters  are:  0,  1,  2 

, 3, 

4,  5,  6.,\7,  8, 

9,)A,  B,  C,  D,  E,  F. 
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TOPIC  B.5  - DATA  BASE  EXECUTIVE  IIST  PROCESSOE 


A.  HODULE  RAHE 

Data  Base  Executive  list  Eunctions  and  Statements 
Program  “ID  ~ RDBI-IST 
Module-ID  “ #LIST 

Entry  points  - DBPAC,DBPACP,DBGLKK,DBGlIK,DBGLKIr 

DEGL-K0,DBS1L1,DB6IKS,DBP1IK,DUP1IST, 
OUST, LIST 

B.  ANALYST 

Garth  B*  Nyman 
Keoterics , Inc , 

C.  HODULE  EUNCTIONS 

EDBLIST  performs  services  on  lists  (of  keys  in  main 
storage)  which  do  not  require  access  to  a data  base* 
^Services  requiring  access  to  a data  base  are  done  by 
module, EDBPAC)  The  list  services  are:’ 

1,  Getting  the  number  of  keys  in  a list, 

2,  Getting  a key  from  a list  in  various  ways, 

3*  Building  a new  list  like  or  from  an  old 

list, 

4.  Boolean  combination  of  two  lists,  and 
5* . Freeing  a list  or  all  lists. 

There  are-  two  means  by  which  mainline  PL/I  programs  use 
the  DBLIST  services: 

’ 1,  By  function  reference.  The  #1IST,*  DUPLIST,  ULIST 
and  LIST  functions  are  invoked  by  reference  in  a 
PL/I  expression. 

2., . By  use  of  DBPL/I,  The  other  services  are  all  used 
by  having  DBPL/I  statements  in  a PL/I  program* 
(See  the  DEPL/I  Language  Extension  User’s  Guide, 
Section  8,  Topic  B*2.)  These  are  processed  at 
compilation  time  by  the  DB  preprocessor  function 
which  transforms  DBPL/I  statements  into  normal 
PL/I  CALL  statements.  {See  the  DBPL/I  - DBLIST 
Interface,  Section  3,  Topic  B.  10.)  At  execution 
time  the  various  entries  of  DBLIST  are  called  for 
the  various  services. 
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D,  DfiTJ  EEQUIEEHENTS 

See  the  DBP1-/I  language  Extension  User’s  Guide, 

Section  8,  Topic  B.2, 

E,  PHOCESSING  KEQUIBIHEUTS 

1.  Top  Level  Flowchart 
Not  Applicable 

2,  Narrative 

The  routines  all  receive  their  parameter  values  as 
specified  in  the  DBPL/2  - DELIST  Interface  because 
the  DB  preprocessor  function  generates  a DSCLAHE 
of  the  entry  points  and  their  parameter 
attributes. 

The  routines  all  recognise  if  a list  pointer 
parameter  has  the  NULL  value  and  process 
accordingly. 

The  routines  all  handle  lists  having  continuation 
segments  by  stepping  from  segment  to  segment  as 
necessary.  In  this  regard  DBLIST  has  three 
internal  subroutines: 

a,  GET  Tjhich  gets  the  next  sequential  key  from  a 

(segmented)  list.  

b,  PUT  which  appends  a new  key  to  a (segmented) 
list  possibly  allocating  and  CHAINing  a new 
segment, 

c,  CHAIN  which  connects  a new  list  segment  to 
the  previous  segment, 

Nhen  the  routines  detect  any  logic  error,  they 
post  an  error  code  number  in 

LISTEB5, EBROB.OHCODE.  Then  if  the  user  has  done  a 
DBPL/I  ON  LISTEBEOE  statement,  a return  is  made  to 
the  user’s  error  routine.  Otherwise,  the  PL/I 
BEROE  condition  is  raised, 

#LIST  is  a function  entry  that  accumulates  and 
then  returns  the  current  count  of  keys  in  a 
(segmented)  list, 

LIST  is  a function  entry  that  compares  the  keys  in 
two  given  (segmented)  lists  and  builds  a 

(segmented)  list  to  return  consisting  of  the  union 
(the  OR  operation)  or  the  intersection  (the  AND 
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operation)  or  the  difference  (the  MIHDS  operation) 
of  the  tiifo  given  lists.  For  the  OE  operation,  if 
one  list  is  well  then  the  other  list  pointer  is 
retnrned  iTnmediatelj.  For  the  HINUS  operation,  if 
either  list  is  null  then  the  first  list  pointer  is 
returned  immediately  without  building  a copy. 

DBFSC  is  an  entry  that  systematically  deallocates 
all  list  segments  for  a subtask  thus  freeing  all 
lists. 

DBPACF  is  an  entry  that  deallocates  the  segments 
of  one  list  and  unchains  them  from  the  chain  for 
the  subtask.  Deallocation  is  not  done  if  the 
LIST.  PEBM  AN  BEIT  flag  has  been  turned  on. 

DBGIKH  is  an  entry  that  gets  the  key  specified  by 
a subscript  from  a (segmented)  list.  If  the 
subscript  is  zero  or  too  high,  the  list  is  reset 
and  a null  string  returned.  If  the  subscript  is 
any  negative  value,  then  the  previous  key  is 
returned  (except  if  the  list  was  reset  then  the 
last  key  is  returned  or  if  the  first  key  was 
current  then  the  list  is  reset  and  a null  string 
returned) . 

DBGIKI  and  DBGIIK  are  entries  that  get  the  next 
key  from  a (segmented)  list  (except  if  the  list 
was  reset  then  the  first  key  is  returned  or  if  the 
last  key  was  current  then  the  list  is  reset  and  a 
null  string  returned) . DBGLKI  will  call  a 
conversion  routine  for  the  key  value  (if 
specified) ; DBGIIK  always  returns  the  unconverted 
interval  key  value, 

DBGIKC  is  an  entry  that  resets  a (segmented)  list 
so  that  the  first  (or  last)  key  will  be 
available, 

DBSIIL  is  an  entry  that,  allocates  the  first 
segment  for  a new  list  and  initializes  it  to  be 
like  an  existing  list  (except  that  it  has  no  keys 
yet) . 

DBGIKS  is  an  entry  that  copies  the  current 
internal  key  from  a (segmented)  list  to  the  end 
of  another  ccmpatible  (segmented)  list, 

DBPilK  is  an  entry  that  puts  an  internal  key  value 
at  the  end  of  a (segmented)  list, 

D0P1IST  is  a function  entry  that  returns  a copy  of 
a (segmented)  list.  Ihe  copy  is  ’’condensed",  that 
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is,  it  has  full  maximum  size  segments. 

ULIST  is  a function  entry  that  steps  through  the 
keys  of  a (segmented)  list  checking  for 

duplicated  internal  key  values.  If  none  are 
found,  i.e.  the  keys  are  unique,  the  list  pointer 
is  returned  without  building  a copy.  If 

duplicated  keys  were  found,  a copy  of  the  list 
having  only  a single  instance  of  any  keys  that 
were  duplicated  is  returned.  The  copy  is 

’’condensed”,  i.e.  it  has  full  maximum  size 
segments. 

CODIHG  SPECIFICATIONS 
-1,  Source  Language 
PL/I. 

The  LIST  and  LISTEBE  declarations  are  included 
from  the  SOPBCEB. LISHHAC  dataset. 

No  Assembler  routines  are  used, 

2,  Suggestions  and  Techniques 

The  internal  procedures  GET,  PUT  and  CHAIN 
simplify,  standardize  and  expedite  key  by  key 
processing  of  segmented  lists. 
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TOPXC  B.6  - DATA  BASE  EXECUTIVE  PAEEHT  - CHIIDEEB  PSOCESSOE 


A*  HODULE  BAME 

Data  Base  Executive  Pareut  and  Children  list  Punctions* 

Program-ID  - ECCIIST 

Hodule-ID  - CCLIST 

Entry  points  - DP1IST,CP1IST 

B.  ANALYST 

Garth  B*  Syman 
Neoterics,  Inc. 

C.  HODULE  PDNCTION 

SCCLIST  builds  a list  of  children  {or  parent)  keys  in 
main  storage  from  a list  of  parent  (or  children) 
keys; 

Hainl'ine  Pl/I  programs  use  the  ECCLIST  services  by 
function  reference  in  a PL/I  expression. 

D.  DATA  REQUIBEHENTS 

See  the  DBPL/I  Language  Extension  User’s  Guide r 
Section  8.  Topic  B.2, 

E.  . PROCESSING  SEQUIEEMEBTS 

1.  Top  Level  Plowchart 
Not  Applicable 
2. . Narrative 

The  routines  all  receive  a MPCE  (Mainline  Pile 
Control  Block)  as  their  first  parameter.  They 
pass  it  though  when  they  call  RDBPAC,  ECCIIST *s 
second  parameter,  a subfile  control  field  name, 
is  posted  in  HICB.OBPIBLD  for’  BDBPAC.  The 
routines  all  receive  a list  pointer  parameter.  If 
it  has  the  NULL  value,  they  return  a NUIL  list 
pointer  immediately. 

Then  BEAD  PILE  LIST  KEY  (0);  is  done  to  reset  the 
BEAD  cursor  of  the  input  list  and  the  list’s  key 
field  name  is  compared  -with  the  anchor  key  field 
name  in  the  core  descriptor  tables.  For  CCLIST 
they  should  be  equal  (the  input  list  should  be  an 
anchor  key  list) ; if  unequal,  the  input  list 
pointer  is  returned  immediately.  For  CPLIST  and 
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OPIIST  they  should  differ  (the  input  list  should 
be  a subfile  key  list) ; if  egual,  the  input  list 
pointer  is  returned  immediately, 

The  #LXST  function  is  invoked  on  the  input  list  to 
obtain  the  count  to  govern  further  processing. 

For  the  CCIIST  function  BEAD  PILE  LIST  EOLOCK  is 
done  iteratively  to  process  all  (parent)  records 
in  the  input  set.  Prom  each  one  a GET  PILE 
SDBPILE  LIST  SET  is  done  using  the  second 
parameter  for  the  subfile  name.  This  returns  a 
list  pointer  to  a temporary  set  consisting  of  the 
subfile  control  field.  If  it  is  nullr  control 
loops  back  to  the  next  BEAD  and  GET,  If  it  is  the 
first  non-null  control  field  encountered,  it  is 
made  the  basis  for  the  output  list.  If  it  is  a 
subseguent  ncn-null  control  field  it  must  be 
merged  with  the  previous  output.  If  its  first  key 
is  higher  than  the  last  key  of  the  previous  output 
(usually)  the  temporary  set  segment  is  appended  or 
the  last  segment.  Otherwise  (rarely)  the  OR  LIST 
function  of  the  RDBLIST  module  must  he  invoked  to 
perform  the  merge  and  then  the  temporary  sets  must 
be  freed.  Control  loops  back  until  all  the  READ 
and  GET'S  have  been  processed.  The  output  list 
pointer  is  returned. 

Pox  the  UPLIST  and  CPIIST  functions  a switch  is 
set  indicating  whether  duplicate-keys  are  to  he 
dropped  after  the  parent  list  has  been  built  by 
code  common  to  both  entry  points.  One  or  more 
list  segments  of  up  to  32767  bytes  of  keys  are 
allocated  and  initialized  as  necessary  to  hold  as 
many  parent  keys  as  there  are  suhr'ecord  keys  in 
the  input  list,  READ  FILE  LIST  NOLOCK  is  done 
iternatively  to  process  all  subrecords  in  the 
input  set.  Prom  each  one  the  internal  parent  key 
value  is  extracted  and  posted  to  the  output 
list. 

If  the  output  list  has  only  one  key,  its  pointer 
is  returned  for  either  DPLIST  or  CPIIST, 
Otherwise  the  output  list  must  be  sorted  into 
ascending  ccllating  sequence.  For  the  CPLIST 
function  the  output  list  pointer  is  returned  at 
this  point. 

For  fhe  UPLIST  function  a final  pass  over  the 
output  list  is  made  to  detect  any  duplicate 
keys.  Each  time  a duplicate  key  is  found  it  is 
deleted  by  shifting  the  remainder  of  the  segment 
to  the  left  and  decrementing  the  segment  count. 
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(This  leaves  a non-compressed  list.)  The  oatput 
lis-fc  poin-ter  is  returned, 

CODING  SPECIPICATIONS 

1,  Source  Language 
Pl/I 

The  IIST  and  LISTEEP  declarations  are  included 
froiD  the  SCOBCE,  LISBHAC  dataset.  Declarations 
for  HFCB,  DISC,  DESC^FLD  and  PCB  structures  have 
been  taken  from  the  source  for  EDBPAC, 

No  assembler  routines  are  used, 

2,  Suggestions  and  Techniques 

The  name  conflict  between  the  LIST  structure  and 
the  LIST  entry  to  EDBLIST  (which  may  be  invoked 
from  ECCLIST)  can  be  circumvented  by  using  PI/I 
preprocessor  facilities  to  rename  the  LIST 
structure  LISS  during  the  compilation. 


PAGE  128 


TOPIC  C. 1 - DTIIITIES  JOIH  (SDBJOIN) 


A.  . IlODDXE  NA{5I 

Joining  ne^r  NASIS  users 
Program-ID  - EDBJCIN 

module-entries  - EBJOIN,  JOIND»  PAGEEE 

B.  ANAXYST 

Edward  J,  Scheboth,  Jr, 

Neoterics,  Inc, 

C.  HODBXE  EUECTIOB 

This  prograiH  gives  the  NASIS  DBA  the  ability  to  create 
and  maintain  the  data  set  NASIS, USEEIDS,  This  data  set 
contains  the  NASISIDS  under  which  users  of  the  NASIS 
system  are  given  access  to  HT/T,  the  Retrieval  system 
and  the  various  data  bases.  The  data  set  NASIS. USEEIDS 
is  organi-zed  under  YISAH,  and  has  as  a key  composed  of 
eight  byte  NASISID  of  each  joined  user,  with  a variable 
record  format  containing  his  password,  timeslice,  user 
authority,  and  list  of  permitted  files. 

This  pregram  has  as  a secondary  function  the  task  of 
displaying  for  rdbinit  the  files  available  for 
retrieval  to  a specific  user, 

-D,  DATA  SEQOIEEHENTS 

1,  I/O  Block  Diagram 
See  figure  1 

2,  Input  Bata  sets 

a.  Parameter  cards 
Not  Applicable 

b.  Punched  Card  Input  Piles 
Hot  Applicable 

c.  Input  Piles 

The  NASISIDS  data  set,  (Por  complete 
detailed  specifications  of  this  file  see 
Section  III  of  the  Development  Workbook) 

d.  On-line  Terminal  Entries 
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Valid  JOIN  coiDinaiids* 

3,  Oatput:  Data  Sets 

a.  Output  Piles 
See  2,c 

i.  On-line  Terminal  Displays 
See  =2,d 

c.  Formatted  Print  Outs 
Not  Applicable 

4*  PuncKed  Card  Output  Files 
Not  Applicable 

4,  • Deference  Tables 

Not  applicable 
PROCESSING  SEQDISEHENTS 

1.  Top  Level  Flovcbart 
See  Figure  2 

2,  Narrative 

The  primary  entry  point  of  this  program  (DBJOIN) 
is  responsible  for  maintenance  and  display  of  the 
NASIS, USERIDS  file. 

The  main  routine  has  a prompt  validation  loop 
which  calls  the  subordinate  functions  such  ' as 
Join,  Quit...  etc.  making  the  program  more  modular 
and.  much  easier  to  modify.’ 

Program  termination  is  thru  the  common  END 
convention  set  up  in  TS/2.  All  parameters  to  the 
commands  shall  be  obtained  using  the  cea  TS/2 
facilities. 

The  secondary  entry  point  of  this  routine  (JOIND) 
displays  the  available  files  for  DBINIT.  , This  is 
really  a sub  function  of  the  main  routine's 
Display  function  and  paging  entry  and  should  be 
coded  as  such  to  facilitate  coding. 


CODING  SPECIFICATIONS 
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1,  Source  Xatiguage 

as  tBuch  as  possible  of  the  BDBJOIN  module  Is  coded 
in  the  IBM  Pl/1  programming  language*  The  input 
and  output  coding  for  accessing  the  file 
NASIS* OSEHIDS  is  handled  by  a direct  call  to  the 
DBPAC  assembler  routines.  All  terminal  access  is 
handled  by  TS/-2, 

2,  Suggestions  and  Technigues 

Befer  to  Section  III  of  the  Development  Workbooh 
for  all  data  set  specifications. 


^ C 
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TOPIC  C.2  - MESSAGE  EII-E  EDITCE 


A.  HODDLE  MAHE 

Enter  new  EXPLAIN  text  into  LISEMLE 
Program-ID  - SEBMII 
Module-IB  - DBKLE 

B.  ANALYST 

George  E.  Oswald 
Heoterics,  Inc, 

C.  HOEniE  JUNCTION 

DBMIP  will  enable  a systems  programmer  to  enter  NASIS 
EXPLAIN  text  into  a library  similar  and  replaceable 
with  LISELIB  (IISEHXE) . A person  may  copy  IISEMLE  into 
a VISAH  file,  BDEE  it  with  the  DDNAME  of  LISRHLF, 
perform  editions  to  it  with  DBBLP,  and  test  the  new 
editions.  Upon  approval,  the  editions  may  replace  the 
original  IISEHLP  member  of  LISELIB, 

The  module  will  perform  interactive  editions  consistent 
with  TS2  conventions.  The  edit  commands  will  provide 
the  user  the  capability  to  ADD,  DELETE,  REPLACE,  and 
DISPLAY  a message;  tc  PFEPIX  (set  the  filter  pref ixl  :■ 
and  to  END  (terminate  editions) • 

D.  DATA  REQUIREMENTS 

1.  I/O  Bloch  Diagram 
See  Figure  1 

2,  Input  Data  Parameter  Cards 
Not  Applicable 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  input  file  will  be  a YISAH  copy  of  the 
current  LISRLIB (LISRHLF) . 
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d.  On-Xine  Terminal  Entries 

All  entries  vill  be  either  command  and 
parameters  or  command  only;  the  form  of  the 
entries  is  either  full  words,  codes,  or 
no-entr-y,  A default  is  made,  where  possible, 
when  no-entrj  is  made.  Prompting  for  new 
command  or  parameters  will  occur  whenever 
necessary. 

3.  Output  Data  Sets 

a.  Output  Piles 
Not  Applicable 

b.  Cn-Xine  Terminal  Display 

All  cn-'line  terminal  displays  for  DBHXE 
follow  the  same  format.  All  such  displays 
are  handled  by  TSPX/I  commands, 

c.  formatted  Print-Outs 
Not  Applicable 

d.  Punched  Card  Output  Piles 
Not  Applicable 

PSOCESSING  PEQDIEENENTS 

1,  Top  level  flowchart 
See  Figure  2 

2,  Narrative 

a.  The  purpcse  of  DBHXP  is  to  provide  a system 
programmer  the  capability  to  ADD,  DELETE, 
BEPLACi,  and  DISPLAY,  NASIS  EXPLAIN  text. 
The  program  is  an  interactive  command-driven 
maintenance  routine  which  creates  a library 
similar  and  replaceable  with  LISBIIB 
(IISEMLP) , 

b.  Kainline  (Prompt  and  validation  Boutine) 

This  routine  is  entered  externally  from 
program  execution  and  internally  upon  command 
completion  and  error  detection. 


1 


Program  Execution 
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The  tiser  will  he  prompted  to  enter  a 
command.  The  user  has  the  option  of 
entering  either  a command  plus 
parameters  or  only  a command.  The 
routine  sill  then  validate  the  entire 
command  string.  However,  if  a parameter 
is  in  error,  the  user  will  be  notified 
and  prompted  to  re-enter  the  particular 
parameter.  If  a no-entry  is  detected 
for  a parameter,  the  parameter  will  be 
defaulted,  or  if  it  is  a mandatory 
parameter,  the  user  will  be  prompted  for 
the  required  parameter.  As  each 
parameter  is  accepted  or  defaulted,  an 
entry  will  be  made  in  the  command 
argument  data  string.  The  command 
itself  will  be  used  to  determine  which 
command  processor  is  to  be  invoked. 

2.  Command  Completion 

Upon  completion  of  a command  the  user 
will  be  notified  of  its  success  full 
termination,  and  prompted  for  a new 
command  or  parameters.  If  the  new  entry 
contains  a command  keyword  {ADD,  DELETE, 
etc.) , then  execution  will  continue  as 
described  above  {E,2.b,  1),  • If  the  new 
entry  is  not  a command  keyword,  then  the 
program  will  assume  the  .new  entry  is  to 
be  processed  as  prescribed  by  the 
previous  command. 

3,  Error  Detection 

If  an  error  has  occurred  during 
subsequent  processing  of  the  command 
argument  data  string,  the  user  will  be 
notified  of  the  error  and  the  user  will 
be  prompted  for  a new  entry  as  described 
in  2 above. 

Command  Processor  Boutines 

There  are  two  unique  forms  of  the  command 
processors:  Group  1 contains  the  commands 
that  cause  file  access;  they  are  ADD, 
REPLACE,  DISPLAY,  and  DELETE.  Group  2 
contains  program  or  data  control;  they  are 
PBEEIX  which  sets  the  filter  prefix  but 
causes  no  access  to  the  file,  and  END  which 
causes  program  termination. 
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File  Access 

The  file  access  coniraanas  have  two  forms: 
those  TJhich  -write’  or  rewrite  data  and 
those  which  read  or  delete  data, 

a.  ^rite  or  Bewrite 

These  commands  require  a source  key 
plus  new  text  information, 

•1 . ADD 

The  ADD  command  will  specify 
■with  the  type  parameter  the 
position  into  which  the  new 
text  is  to  be  placed;  example, 
within  ID,  MSG  parameter 
preempts  line  numbers  0 
through  99  in  increments  of 
5,  EXP  parameter  preempts  line 
numbers  100  through  199  in 
increments  of  10,  and  the  EESP 
parameter  preempts  line 
numbers  400  through  999999-9. 
The  lack  of  one  of  the  above 
qualifying  params  designates 
the  type  and  text  of  the 
command  argument  data  string 
designates  an  -explanation  of 
■ a file  oriented  term  or  a 
global  term.  This  form  causes 
a default  to  the  next 
available  line  number  within 
that  region. 

Mote  that  when  positioning  for 
adding  a record  to  the  file 
and  a line  number  is  not 
specified,  a read  will  be 
attempted  using  the  highest 
line  number  possible  within 
the  above-mentioned 
specification  and  thus  provide 
the  line  number  of  the ■ last 
record  within  type  or  term 
within  the  region. 

In  combination  with  the  type 
param  the  line  number  may  be 
specified;  this  combination 
denotes  a line  to  be  inserted 
within  type  or  term,  and 
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within  region.  , 

When  the  new  line  number  has 
been  established,  the  source 
key  will  be  complete  and  a 
write  of  the  new  line  will  be 
initiated.  Mote:  the  writing 
of  a new  data  line  can  cause  a 
duplicate  key  error  condition; 
this  condition  will  be  handled 
by  a separate  routine. 

2.  SEP 

When  a request  is  made  for  a 
line  to  be  replaced,  all 
params  are  mandatory.  The 
routine  will  first  construct 
the  source  key  and  then 
initiate  a read.  Successful 
completion  of  the  read 
determines  that  there  is  an 
existing  line  to  be  replaced, 
A key-not-found  condition 
denotes  that  an  invalid  line 
number  was  supplied  in  the 
command  argument  data 
string. 

Kote:  The  existence  of  a 
key-not-found  condition  will 
cause  • an  entrance  into  the 
error  handling  routine. 

The  data  line  obtained  by  the 
read  will  be  replaced  as 
denoted  in  the  command 
argument  data  string,  and  a 
rewrite  will  be  initiated. 
Note;  There  are  no  valid 
exceptions  for  the  failure  or 
the  rewrite  statement. 

Read  and  Delete 

These  commands  do  not  manipulate 
the  data  file  per  se,  but  provide 
for  deleting  or  displaying  of  text 
within  the  delimeters  provided  by 
the  command  argument  data  string. 

In  both  commands  only  the  ID  param 
is  mandatory;  therefore,  it  is 
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possible  for  a commancl  to  request 
the  deletion  or  display  , of  text 
from  a single  line  number  to  an 
entire  ID. 

1.  DELEIE 

Delete  will  obtain  the 
delimeters  from  the  command 
argument  data  string  and 
remove  all  references  to  the 
text  as  specified  by  the 
delimeters.  Note;  Ihere  are 
no  valid  exceptions  for  the 
failure  of  the  delete 
statement. 

2.  DISPLAY 

Display  will  obtain  the 
delimeters  from  the  command 
argument  data  string  and 
display  all  references  to  the 
text  as  specified  by  the 
delimeters.  When  expiration 
of  the  delimeters  occur  and/or 
no  data  is  available  for 
displaying,  a message  will 
return  notifying  the  user  of 
the  condition. . Note:  The 
key^not-f ound  condition  will 
be  used  to  determine  the 
expiration  of  the 
delimeters. 

Control  Commands 

There  are  two  control  commands 
provided. 

1.  PSEFIX 

The  PBEFIX  command  provides 
for  the  setting  of  the  filter 
prefix  for  each  line  to  be 
added  or  replaced. 

Note;  The  prefix  code  in  the 
command  argument  data  string 
will  be  ignored  by  all  other 
command  processor  routines. 
Once  the  prefix  command  is 
issued,  it  will  remain  in 
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affect  for  all  ADEs  and  ESPs 
ccmmands  until  a subsequent 
prefix  command  alters  the 
setting  of  the  filter 
prefix. 

2*.  EMD 

An  orderly  close  of  all  files 
will  occur  and  the  program 
will  terminate, 

CODIHG  SPECIFICATIONS 
1.  Source  language 
Not  Applicable 
Suggestions  and  Techniques 
Not  Applicable 


2.. 


PREFIX 


□L 

SUPPLY  PREFIX 
CRITERIA 
TO  DATA 
STRING 

' 

1 

GO  TO 
PROMPT 


Figure  2.  Top  Level  Flowchart 
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TOPIC  C,3  - C0K7EBS10H  ANE  lOBMATTIUG  ROUTINE  TEST  DRIVER 

A.  MODULE  NAME 

Conversion  and  Formatting  Routine  Test  Driver 
Program-*ID  - RDBDBIVE 
Module-ID,  - DBDRIVF 

B.  ANALYST 

James  A«  Wesley 
Neoterics,  Inc, 

C.  MODULE  FUNCTION 

RDBDSIVE  is  a facility  to  allow  the  application 
programmers  to  test  conversion,  validation  and 
reformatting  routines  conversationally.  The  user  can 
specify  the  routine  names  and  input  data  values  to 
simulate  the  activities  of  EDBPAC, 

D.  DATA  REQUIREMENTS 

1,  I/O  Bloch  Diagram 
See  Figure  1 

2,  Input  Bata  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c,  Inpuf  Files 
Not  Applicable 

d,  'On-line  Terminal  Entries 

The  user  is  prompted  for  all  the  input  data 
required . 

3,  Output  Data  Sets 


a. 


Output  Files 
Not  Applicable 
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b.  • On-line  Terminal  Bisplays 

All  input  data  is  displayed  to  the  user  for 
verification  in  two  forms;  in  the  form  as 
entered,  and  after  any  necessary  conversion. 
The  output  from  each  routine  is  displayed  in 
hexadecimal,  and  the  output  from  reformatting 
routines  is  also  displayed  in  its  character 
form, 

C.  formatted  Print-outs 
Kot  Applicable 

d.  Punched  Card  Output  files 
Not  Applicable 
4,  Reference  Tables 
Not  Applicable 
PROCESSING  BEQUISEKENTS 

1.  Top  Level  Flowchart 
See  figure  2 

2,  Narrative  • 

The  user  is  prompted  to  enter  the  input  mode,  this 
is  the  mode  which  the  character  string  he  enters 
at  his  terminal  will  be  converted  into  before 
imputing  it  to  his  selected  routine (s).  The 
possible  input  modes  are: 

a = alphanumeric, 
f = full  word, 
h = half  word, 
p = pached  decimal, 

1 = long  floating  point, 
s = short  floating  point, 

X = hexadecimal. 

A null  response  to  this  prompt  is  the  only  way  out 
of  the  module.  Null  responses  to  any  other  prompt 
will  eventually  filter  back  to  this  prompt. 

The  type  of  inpnt  mode  selected  determines  the 
setting  of  a label  subscript  which  is  later  used 
to  branch  to  the  routine  necessary  to  convert  the 
input  data  to  the  selected  mode. 
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Tlie  user  is  next  proinptea  for  the  routine  names* 
They  must  be  entered  in  one  string,  separated  by 
commas,  and  must  not  exceed  eight  characters.  A 
null  response  here  returns  to  the  prompt  for 
input  mode.  Also,  the  routine  names  must  be 
entered  in  the  order;  conversion,  validation, 
reformatting,  and  any  missing  routines  must  be 
defaulted;  eg: 

EBCVTSfi, ,DBFHTSN 
or 

,,,DBFHTHX 

If  a validation  routine  has  been  specified,  the 
user  is  prompted  for  the  validation  arguments. 
These  can  be  any  character  string,  up  to  a maximum 
of  50  characters;  or  null. 

The  user  'is  now  prompted  for  input  data,  A null 
response  here  returns  to  the  prompt  for  routine 
names.  The  input  data  is  converted  to  the  mode 
selected  by  the  user. 

The  data  is  new  passed  to  all  the  routines 
specified,  in  the  order;  conversion,  validation, 
reformatting.  The  output  from  one  routine  is  used 
as  the  input  to  the  next  routine. 

The  output  from  each  routine  is  displayed  in 
hexadecimal  and  the  output  from  the  reformatting 
routine  is  also  displayed  in  character. 

Successful  completion  returns  the  user  to  the 
prompt  for  data.  Any  error  results  in  a 
diagnostic  message  and  the  return  to  the  prompt 
for  data. 

CODING  SFECIFICATIGNS 

1,  Source  language 

This  module  is  coded  in  the  IBiJ/360  PlI  language. 
The  TSP1-/I  language  Extension  i-s  used  for  all 
terminal  I/O, 

2.  Suggestions  and  Techniques 
Not  Applicable 


Figure  1,  I/O  Block  Diagram 
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Figure  2.  Top  Level  Flowchart 
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TOPIC  C.4  **  DTIIHIES  BOSEBID 

A.  MODULE  NAME 

Get  the  TSS  USEEID 
Program-ID  - BUSEEID 
Module-ID  - DSEBIE 

B.  ANALYST 

John  A«  Lozan 
Neoterics,  Inc, 

C.  MODULE  FUNCTION 

This  program  is  used  to  obtain  the  TSS  userid  and  save 
its  value  in  the  TSS  profile  as  a default  for  the 
symbol  USEEID,  This  symbol  is  then  used  during 

USEEJOIH  to  create  the  transaction  and  statistics 
files, 

D.  DATA  REQUIEEMENTS 

1,  I/O  Block  Diagram 
Not  Applicable 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Hot  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Hot  Applicable 

d.  On-lire  Terminal  Entries 
Not  Applicable 

V 

3,  Output  Data  Sets 

a.  Output  Files 
Net  Applicable 

b.  On-line  Terminal  Displays 
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Not  Applica33le 
c,  lormatted  Print-Outs 
Not  Applicable 
4«  Seference  Tables 
Not  Applicable 
PBOCESSING  BEQTJISIHEKTS 
1.  Top  level  llowchart 
See  Figure  1 
2«  Narrative 

Upon  entry,  norroal  TSS  linKage  reguixements  are 
fulfilled.  Next,  the  program  uses  the  XTBCT 
macro  to  obtain  the  userid  of  the  taslc  being 
executed.  The  trailing  asterisks  are  removed  from 
the  userid  and  the  resultant  value  is  assigned  to 
the  default  symbol  USEBID  and  posted  in  the 
user’s  TSS  profile  by  means  of  the  OBEY  macro. 
The  program  then  returns  to  its  caller. 

CODING  SPECIFICATIONS 

1,  Source  language 

Because  of  its  use  of  TSS  system  functions,  this 
module  is  coded  in  the  TSS/360  - assembler 

language. 

Suggestions  and  Technigues 
Not  Applicable 


2 


Figure  1.  Top  level  flowchart 
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TOPIC  D. 1 “ HAIKTENANCE  TBANSACTIOK  MERGE 


A.  MODULE  HAHE 

Maintenance  - Transaction  Merge 
Program-ID  - RDBMIBGE 
Modnle-ID  - DEMERGE 

B.  ANAIYST 

Richard  D.  Graven 
Neoterics,  Inc. 

C.  MODULE  JUNCTION 

This  module  is  responsible  for  taking  the  contents  of 
the  various  userids*  transaction  data  bases  and  merging 
all  of  the  transactions  affecting  a particular  data 
base  into  the  transaction  data  base  of  the  data  base 
owner.  The  resultant  combined  set  of  transactions  is 
then  processed  by  Maintenance  itself. 

The  input  transaction  data  basees  are  shared  with 
read/write  access  to  the  data  base  owner  to  enable  him 
to  delete  each  transaction  as  he  copies  it  over. 

D.  . DATA  REQUIREMENTS 

1,  I/O  Block  Diagram 

See  figure  1 

2.  ■ Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b»  Punched  Card  Input  files 
Not  Applicable 

c.  Input  files 

Tbe  two  possible  sources  of  input  for  this 
program  are,  <1),  the  VISAS  dataset  which 
contains  the  list  of  TSS  userids  which  have 
been  joined  to  the  NASXS  system,  and  (2)  the 
transaction  data  bases  of  the  NASIS  system 
users. 

d.  On-line  Terminal  Entries 
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Kot  Applicable 

3,  Output  Data  Sets 

a.  Output  Piles 

Ihe  ouIy  output  file  used  by  the  program  is 
the  transaction  data  base  of  the  o«ner  of 
the  data  base  whose  transactions  are  being 
merged. 

b.  On-line  Terminal  Displays 

Standard  prompting  messages  are  directed  to 
SYSOUT,  as  are  all  error  messages  written  by 
the  program. 

c.  Pormatted  Print-outs 
Not  Applicable 

d.  Punched  'Card  Output  Piles 
Not  Applicable 

4,  Eeference  Tables 

a special  table  is  used  by  the  program  to  control 
the  input  files  to  be  processed.  This  table  is 
built  by  -the  program  at  initial  entry  from  the 
special  input  file  containing  the  names  of  all  TSS 
userids  which  have  been  joined  to  the  system, 

PBOCESSING  SEQUIBEHEHTS 

1.  Top  level  Plowchart 

See  figure  2 

2. , Narrative 

a.  Initialize 

The  routine  opens  the  dataset  containing  the 
list  of  TSS  userids  joined  to  the  system. 
This  dataset  is  read  sequentially  and  each 
entry  is  placed  in  the  name  table  for  future 
reference.  When  the  end -of -file  is  sensed 
for  this  dataset,  it  is  closed  and  normal 
execution  continued. 

The  final  function  of  this  routine  is  to  open 
the  transaction  data  base  of  this  userid  for 
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direct  output, 

c,  cpen  Input 

ihis  routine  uses  the  data  base  name  and  the 
next  entry  in  the  name  table  to  construct  the 
name  of  a transaction  data  base,  which  it 
then  attempts  to  open  for  direct  update.  Any 
errors  cause  a diagnostic  to  be  written  and  a 
bypass  of  that  file,  The  routine  then 
constructs  the  lowest  value  key  possible  for 
that  userid  and  the  specified  data  base  and 
attempts  to  read  that  record. 

d.  Copy  Becord 

This  routine  performs  a seguential  read  of 
the  input  transaction  data  base.  The  record 
key  of  the  transaction  read  is  examined  to 
ensure  that  it  applies  to  the  data  base 
specified.  If  not,  control  is  passed  to  the 
Close  Input  routine.  Once  the  transaction 
has  been  validated  it  is  written  to  the  data 
base  owner’s  transaction  data  base  and  then 
deleted  from  the  input  data  base.  Control  is 
then  passed  to  the  beginning  of  this  routine 
for  the  next  record.  Any  DBPAC  errors  that 
are  encountered,  except  end-of-file  on  the 
input  data  base,  cause  program  termination, 
following  an  appropriate  diagnostic 
message, 

e.  Close  Input 

This  routine  closes  the  input  transaction 
data  base.  If  the  entries  in  the  name  list 
have  not  been  exhausted,  control  is  passed 
back  to  the  Open  Input  routine  to  process  the 
next  user’s  transactions.  Otherwise,  control 
flows  to  the  next  section, 

f,  End-of-dcb 

This  routine  closes  the  owner’s  transaction 
data  base.  It  then  returns  to  the  calling 
module, 

CODING  SPECIPICATIONS 
1,  Source  Language 

The  Herge  program  employs  the  IBH  PL/I  programming 

language.  The  special  extensions  of  that 
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language,  called  DBPI-/I'  and  TSPl/I,  are  utilitzed 
for  all  access  to  files  in  the  data  base  and  for 
all  terminal  communication,  respectively. 

Suggestions  and  Technigues 

Not  Applicable 


Figure  1.  I/O  Block  diagram 


]\)  , \l>  ^ ^ 


Td  1 
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TOPIC  D,2  - MAINTENANCE  MAINLINE 


•A.  MODULE  NAME 

Maintenance  Mainline 
Program-ID  - BDBMKIN 
Module-ID'-  DBMNTN 

■B.  ANALYST 

Eichard  D.  Graven 
Ueotericsr  Inc. 

C.  MODULE  FUNCTION 

The  Maintenance  Mainline  program  is  an  independent 
module  which  carries  out  any  actual  changes  necessary 
to  correct,  update,  or  expand  the  files  comprising  a 
data  base.  The  specific  changes,  which  can  be 

additions,  deletions,  or  replacements,  are  accepted  by 
Maintenance  in  the  form  of  transactions.  The 

transactions  are  kept  .on  a data  base  named  ’TENSCT*  and 
are  created  and  maintained  by  the  COEEECT  command. 

The  transactions  can  be  applied  to  the  data  base  on  a 
record,  field,  or  element  basis.  Those  transactions 
which  are  successfully  applied  to  the  data  base  are 
deleted.  Therefore,  after  the  successful  completion  of 
a maintenance  run,  the  only  transactions  remaining  on 
the  ’TENSCT*  da-ta  base  are  those  which  need  correcting. 
The  Maintenance  Mainline  acquires  the  necessary 
statistics  while  executing  and  causes  the  ’STATIC*  data 
base  to  be  updated  (via  a call  to  RDBUPDST) • The 
Maintenance  Mainline  is  run  only  in  background  or  batch 
mode.  The  restart  capability  of  the  maintenance  run  is 
inherent  because  of  the  deleting  transactions  as  they 
are  applied  and  because  the  statistics  are  updated 
after  the  successful  processing  of  each  transaction 
record. 

The  Maintenance  Mainline  then  has  external  interfaces 
with  modules  of  the  usage  statistics.  The  BDBUPDST 
module  is  called  after  the  successful  processing  of 
each  transaction  in  order  to  update  the  maintenance 
statistics. 

D.  DATA  REQUIREMENTS 

1.  I/O  Block  Diagram 


See  Figure  1 
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2.  Input  Data  Sets 

■a«  Parameter  Cards 
Kot  applicable 

b.  Punched  Card  Input  Piles 

While  the  Haintenance  Mainline  is  normally 
invoked  from  a terminal  and,  therefore,  has 
no  punched  card  input,  it  is  also  possible  to 
initiate  the  task  in  the  non-conversational 
mode.  The  maintenance  is  always  a batch 
task.  The  Maintenance  User’s  Guide  describes 
completely  the  procedure  for  invokation. 

c.  Input  Piles 

The  maintenance  program  requires  all  of  the 
files  which  make  up  a data  base  as  input  to 
the  module. 

The  files  in  a data  base  are  the  source  . of 
the  old  or  current  data  for  maintenance,  the 
transaction  data  base  tTRNSCT)  is  the  source 
of  the  new  or  replacement  data  (i.e. , the 
changes) . The  complete  description  of  the 
transaction  queue  is  found  in  the  dataset 
specifications.  The  transaction  data  base 
^TENSCT)  contains  information  concerning  the 
data  base,  file,  record,  field  and  element  to 
be  maintained,  as  well  as  the  type  of 

maintenance  and  the  new  data. 

d.  On-Line  Terminal  Entries 

There  is  basically  only  one  terminal  entry  to 
the  maintenance  routine  and  that  is  the 
command  entered  to  initiate  the  program.  The 
complete  explanation  of  this  procedure  is 
available  in  the  Maintenance  User’s  Guide. 

3.  Output  Bata  Sets 

a.  Output  Biles 

All  of  the  files  of  a data  base  may  be  used 
as  output  files  for  maintenance.  As  in  the 
case  where  the  files  of  a data  base  are  used 
for  input,  the  individual  data  files  are 
output  tiles  only  if  specific  transactions 
reguire  them. 


PiGE  158 


b.  On-line  Terminal  Displays 
Hot  Applicable 

c.  Formatted  Pxint-outs 
Hot  Applicable 

d.  Punched  Card  Output  Piles 
Hot  Applicable 

4, . Before nee  Tables 

Since  DBPl/I  is  used  extensively  in  this  module, 
the  various  combinations  of  DBPAC  errors  should  be 
handled  properly.  These  are  in  an  array  to 
determine  program  processing  after  error  occurs, 

PROCESSING  REQTJIREMEHTS 

1,  Top  Level  PlOKchart 
See  Figure  2 

2.  Narrative 

a.  EDBMNTN  (DBMHTN-entry  point)' 

The  Haintenance  Mainline  program  is  an 
maintenance  module  which  carries  cot  changes 
to  the  files  comprising  a data  base.  The 
program  receives  directives  to  modify  a data 
base  file  or  files  from  the  maintenance 
transaction  data  base  <TRNSCT) , 

b.  Initialization 

A table  of  the  fields  which  are  inverted  is 
created  from  FIDTAB,  The  key  fields 
descriptor  is  read  and  upon  finding  it,  the 
key  field’s  length  is  saved. 

If  any  errors  are  incurred  while  reading  the 
descriptor  file,  the  proper  message  is 
emitted  and  the  run  terminated.  If  not,  then 
the  use  of  the  descriptor  file  is  at  an  end 
and  it  is  closed. 

It  is  now  time  to  initialize  the  transaction 
file  by  opening  it,  positioning  it  and  making 
the  first  record  to  be  processed  available. 
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An  error  on  opening  of  the  transaction  data 
base  conld  mean  that  there  is  no  data  on  the 
*TBSSCT'  data  base,  or  that  the  'TPKSCT* 
dataplex  is  already  opened  for  update  or 
output.  In  either  case,  appropriate  error 
messages  are  issued  and  the  run  is 

terminated. 

To  position  the  data  base  (after  opening) , we 
do  a Read  by  Key  NOIOCK,  The  key  we  create 
consists  of  the  data  base  name  concatenated 
with  the  owners-ID  contatenated  with  all  bits 
off.  This  should  represent  a low  key  value. 
This  yields  cither  a successful  read  or  a 
IBPAC  error  of  108.  Se  expect  the  error  to 
occur.  Then  a sequential  read  is  performed 
and  we  obtain  the  first  transaction  to  be 
processed.  Before  continuing  a get  field  is 
executed  on  the  key  and  its  contents  are 
checked.  If  the  key  does  not  represent  the 
proper  data  base  name,  owner-ID  combination 
an  error  message  is  emitted  and  the  run  is 
terminated. 

Otherwise,  we  are  prepared  for  the  final 
stage  of  initialization. 

The  regular  transaction  data  base  (TSNSCT) 
routine  is  set,  the  data  base  which  is  being 
updated  has  its  error  routine  set  and  it  is 
opened  for  direct  update  or  sequential 
output. 

The  initialization  process  is  complete. 
Updating  Statistics 

The  rules  for  gathering  and  keeping  the 

statistics  for  maintenance  are  as  follows; 

1,  Add  transactions  with  a field  name  egual 
to  the  anchor  files  (TBANCNEP) . 

2,  Add  transactions  with  a field  name  of 

SUB**  will  post  the  new  subfile 
record  count  for  subfiles  (TESUBNEU) * 

3,  Delete  transactions  with  a fieldname 

equal  to  the  anchor  key  name  will  post 
the  delete  record  count  for  the  anchor 
files  (TBABCDEL) . 

4,  Delete  transactions  with  a subkey  field 
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will  pxDst  the  delete  subfile  record 
coant  (TBSUBBEi) . 

5.  Add  transactions  with  a field  name  other 
than  the  key  field  name  will  post  the 
update  count  for  the  anchor  file 
(TBAKCTJPD)  . 

6.  Add  transactions  with  a field  name  other 
than  the  key  field  name  and  a SDBKEY 
field  will  post  the  update  count  for  the 
subfile  file  <TRSDBTJPD)  . 

7.  Change  transactions  will  post  the  update 
count  for  the  anchor  file  (TBANCDPD) • 

8.  Change  transactions  with  a STIBKEY  field 
will  post  the  subfile  count  for  the 
subfile  file  (TBSOBUPD) . . 

S,  If  the  filed  is  inverted  then 

appropriate  index  file  count  will  be 
posted* 

Ihese  statistics  are  accumulated  only  if  the 
transaction  was  successfully  used  to  update 
the  data  base.  The  statistics  data  base  is 
updated  after  each  transaction  has  been 

processed.  This  means  that  if  the  system 
crashes  or  otherwise  fails  during  execution 
of  a given  maintenance  run,  the  statistics 
will  be  correct.  Since  each  transaction 
(after  it  has  successfully  updated  the  data 
base)’  is  deleted  from  the  TEHSCT  data  base, 
then  fhe  restart  procedure  is  automatic. . The 
call  to  the  module  to  update  the  statistics 
is  as  follows? 

CAXl  EBDPDST (DPDTPLAG,BATAPLEX, 
TEAMCNEB,TEANCBEL,TRAHCUPB, 
TESDBHEW,TESUBBEL,TBSUBUPB, 
TEIHV1IEB,TRI1I7DEL,TRINVUPD)  ; 

If  the  statistics  are  updated  successfully, 
the  DEUPDST  module  returns  a ’G’  in  UPDTFLAG. 
If  the  statistics  are  EOT  updated 
successfully,  the  BBOFDST  module  returns  a 
in  the  UEBTELAG, 

d.  Belete  the  Transaction 

If  the  transaction  is  successful,  it  is  now 
deleted  from  the  TBNSCT  data  base. 
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e,  Bead  Transaction 

The  transaction  file  is  a data  base  which 
consists  of  only  an  anchor  file  and  no 
associated  or  inverted  files.  The 
transactions  are  read  sequentially.  The  Data 
Ease  Executive  perforins  all  of  the  necessary 
I/O  operations.  After  a transaction  record 
is  located  by  the  Data  Base  Executive,  GETS 
are  executed  on  all  of  the  desirable  fields. 
These  fields  are  disseminated  to  various 
work  areas.  Then,  checking  is  performed 
based  on  the  presence  and/or  absence  of  data. 
The  validation  of  this  data  is  based  upon  the 
following? 

See  figure  3 

If  there  is  an  error  detected  during  this 
initial  processing,  then  the  transaction  is 
in  error, 

f,  E.O.D,  (end-of-data) 

The  end-of-data  is  only  detected  on  the 
transaction  data  base.  When  this  condition 
is  detected,  all  the  files  are  closed, 
appropriate  messages  are  issued  and  the 
processing  continues  at  the  reset  the 
switches,  section  (g) . 

g,  Beset  the  Switches 

This  section  of  code  is  executed  antecedent 
to  the  occurence  of  an  end-of-data 
conditicn.  The  files  of  the  data  base  are 
manipulated  to  detect  the  existence  or 
non-existence  of  data  and  the  ’DATA’  switches 
of  the  corresponding  files  are  set 
accordingly, 

h,  BBl^BTM;  Delete  field  routine. 

This  routine  uses  the  #FIE1D  function  to 
reput  all  the  elements  in  the  field  to  null. 
If  it  is  the  key  field,  then  the  entire 
record  is  deleted, 

i,  ADD^ETN?  Add  routine. 

This  is  the  add  record  and  add  element 
routine.  If  the  field  name  is  the  key  field 
then  this  name  Is  stored  to  indicate  to  the 
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maintenance  routine  that  a new  record  is  to 
he  added  to  the  file.  If  the  field  is  not 
the  Key  field,  then  a' test  is  made  to  see  if 
the  transaction  Key  is  already  present.  If 
not,  then  the  key  is  compared  to  the  stored 
Key  from  the  last  add  transaction  with  a Key 
field.  If  they  do  not  match,  an  error  has 
occurred  and  is  flagged?  otherwise,  a record 
is  created  with  the  stored  Key.  The  new 
element  is  then  put  to  the  record.  Control 
is  passed  back  to  section  (e)  on  completion 
of  this  transaction, 

NOTE;  If  subfile  key  is  present  in 
transaction  then  subfile  record  is  obtained. 
If  SDBCTI  field  is  present  then  new  subfile 
record  is  located, 

CHG^STN:  Change  Soutine, 

If  no  start  or  end  field,  giwen  element  is 
replaced.  Dsing  the  key  passed  in  the 
transaction  record,  the  appropriate  record  is 
read  in  from  the  data  base.  At  that  point, 
the  value  of  the  returned  field  element  is 
compared  to  the  *old*  data  element  in  the 
transaction.  If  no  match  is  made,  a test  is 
made  as  to  whether  the  returned  element  is 
null,  thereby  signifying  the  end  of  the 
field.  If  that  is  the  case,  then  an  error 
has  occurred  and  is  indicated.  If  the  null 
element  was  not  detected,  then  the  next 
element  is  obtained  and  the  process 
repeated.  If  a match  does  occur,  then  the 
*new*  data  element  from  the  transaction 
record  is  reput  to  the  record.  If  the  *new* 
data  element  is  null,  then  the  element  is 
deleted.  Continue  processing  with  section 
(e) . If  a start  and  end  field  is  present 
then  a field  context  operation  is 
performed, 

Ihe  maintenance  program  can  carry  out  changes 
to  portions  of  large  fields  without  the 
entire  field  on  the  transaction  entry  record. 
To  begin,  the  record  is  read  into  a large 
enough  area  to  hold  the  maximum  record  using 
the  Key  provided  in  the  transaction.  The 
field  in  guestion  will  then  be  obtained  and 
an  interactive  process  is  applied  wherein  the 
*old*  data  value  is  compared  sequentially 
across  the  field  from  the  starting  location 
to  the  ending  location,  TJhenever  a match  is 


PiGE  163 


found r the  *new*  data  value  is  used  to 
replace  the  »old»  in  the  field- and  a count  is 
Kept  of  the  number  of  replacements.  When  the 
end  of  the  search  range  is  reached,  the  count 
is  tested.  If  no  matches  were  made,  then 
that  error  is  recorded.  The  processing  will 
continue  with  section  (e) • 

CODING  SPECIPICailCNS 

1..  Source,  Language 

As  much  as  possible  of  the  Haintenance  Nodule  is 
coded  in  the  IBH  programming  language  PL/I.  The 
input  and  output  coding  for  access  to  files  in  a 
data  base  is  handled  through  an  extension  to  that 
language.  Known  as  DBPL/I.  Where  indicated  in  the 
narrative,  it  was  necessary  to  use  the  assembler 
language  for  IBM  System/360  in  order  to  interface 
with  the  command  processor  and  the  DDBP 
instructions.  All  terminal  communication  is 
handled  through  the  terminal  support  preprocessor, 
TSPL/I, 

2.  Suggestions  and  Techniques 

a.  Much  of  the  verification  of  correct  access  to 
files  in  a data  base  Is  handled  within  the 
DBPAC  routines. 


b.  Curing  implementation,  all  appropriate 

messages  are  included  to  increase  the 

understanding  cf  the  user. 

c.  While  not  noted  in  the  narrative,  it  is 

necessary  to  test  the  return  codes  from 
every  input  and  output  operation.  In  those 
cases  where  errors  occur,  messages  are 
written  cut  and  the  task  terminated  unless  a 
correction  can  be  applied,  in  which  case  the 
processing  can  then  continue. 

d«  Whenever  it  becomes  necessary  to  terminate 
the  maintenance  routine  at  any  point,  it  is 
desirable  to  make  every  attempt  to  restore 
the  data  base  to  a normal  condition.  In  most 
cases,  this  action  involves  resetting  control 
switches  found  in  the  header  records  of  the 
descriptor  file.  This  action  makes  possible 
subsequent  processing  on  the  data  base  which 
might  correct  the  original  problem  and  also 
allows  continued  retrieval  from  all  usable 
portions  of  the  data  base. 
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Figure  2.  Top-level  flowchart 


y : EEQUIRED  PARAMETER 


X : NOT  REQUIRED 
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Figure  3.  Parameter  table 
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50PIC  D.3  - HAIKTENAHCE  COEEECT  COH15AND 


A.  MODULE  HAME 

Maintenance,  CORRECT  Command 
Retrieval,  CORRECT  Command 
Program-ID  - BLBCOIR 
Hodnle-ID  - DBCORR 

Entry  Point  (DBCOSE)  MAINTENANCE 
(DBCORR  1)  RETRIE7A1 

B.  . ANALYST 

Richard  D.  Graven 
Neoterics,  Inc, 

C.  MODULE  FUNCTION 

The  CORRECT  command  is  a routine,  called  by  the 
RETRIEVAL  system,  whose  purpose  is  to  allow  the 
retrieval  system  user  to  create  certain  maintenance 
transactions  during  retrieval.  When  a user  observes  an 
error  during  a display,  he  is  able  to  have  any  or  ail 
of  the  fields  of  a given  record  displayed  and  then  be 
able  to  specify  any  deletions,  additions,  or  changes  to 
those,  fields.  The  transactions  created  are  not 
executed.,  but  are  placed  in  a transaction  data  base 
which  is  examined  by  the  data  base  owner  before  the 
actual  maintenance  takes  place.  The  calling  sequence 
is:  CORRECT  field, key. 

The  CORRECT  command,  when  invoked  through  the 
maintenance  sub-system,  performs  on-line  creation  and 
updating  of  files, 

•D.  - DATA  REQUIREMENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
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Hot  Applicable 

a*  On-line  Terminal  Entries 

The  parameters  available  to  the  COSBECT 
command  are  "key”  and  ’’fieldname"*  The 
Terminal  Snpport  system  applies  default 
values  to  the  parameters,  if  they  are 
available,  when  no  original  values  are 
entered. 

Additional  terminal  entries  are  reguested  of 
the  user*  These  responses  indicate  mhat 
alterations,  if  any,  to  the  field  are 
desired.  These  entries  take  the  form  of 
sub-commands  available  to  the  user  while 
running  under  control  of  COHBECT,  The 

sub-commands  are: 

ADD  data 
CANCEL 

COBEECT  field, <key> 
lElETE  element 
BISPLA? 

END 

FIELDS 

INSEET  field,,.. 

BEPLACE  element 1 ,<element>, olddata<,newdata> 
VEBIFY 

Output  Data  Sets 

a.  Output  Files 

The  only  output  file  from  the  COBEECT  command 
is  the  transaction  data  base.  This  file  is  a 
VISAS  data  set  containing  maintenance 

transactions  from  all  sources  for  all  data 
l)ases.  The  fields  of  the  transaction  data 
base  and  their  format  are  completely 
described  in  the  Dataset  Specifications, 

b.  On-line  Terminal  Displays 

The  COBEECT  command  outputs  a formatted 

display  of  the  specified  field  on  the 
terminal.  Each  field  to  be  processed  begins 
on  a new  screen  image  with  appropriate  header 
information.  Each  element  of  multi-element 

fields  begins  on  a new  line.  No  attempt  is 

made  to  end  lines  of  the  display  on  word 
boundaries.  In  addition  to  the  display  of 
the  field  in  question,  a prompting  message 
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requesting  the  action  to  be  taken  is  issued 
in  the  input  area  of  the  screen. 

c,  formatted  Print-outs 
Hot  applicable 

d.  Punched  Card  Output  files 
Not  Applicable 

4,  Reference  fables 

Not  applicable 

PEOGSAH  EBQUIEEMENTS 

1.  flowchart 

See  figure  2 

2,  Narrative 

a.  CORRECT 

The  CORRECT  command  is  called  by  the 
maintenance  sub-system  at  entry  point  DBCORR, 
The  Retrieval  subsystem  calls  CORRECT  at  the 
entry  point  DBCORR 1,  Any  default  parameters 
which  are  applicable  are  supplied  by  terminal 
support. 

b.  Real  Entry 

This  routine  initializes  the  routines  for 
handling  the  exceptional  error  and  interrupt 
conditions.  Attention  interrupts  cause  the 
user  to  be  prompted  for  a decision.  If  he 
defaults,  execution  continues  from  the  point 
of  interruption.  Terminal  support  prompting 
errors  cause  program  termination,  unless  the 
error  is  for  input  transaction,  in  which 
case,  a warning  message  is  issued  to  the  user 
and  execution  continued.  Any  other  errors 
cause  program  termination,  following  an 
appropriate  diagnostic  message. 

c.  Bain  line 

The  routine  allocates  the  screen  buffers,  if 
not  already  done,  and  obtains  the  julian  date 
for  time  stamping  the  transactions.  The 
current  retrieval  data  base  is  then  opened 
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for  input,  unless  that  data  base  is  the 
user’s  transaction  data  base,  in  which  case, 
it  is  opened  for  update, 

d.  Get  Record 

Tf  necessary,  this  routine  reads  a new  record 
from  the  input  data  base  and  gets  the  value 
of  the  hey  field.  Again,  if  necessary,  the 
routine  reads  in  the  values  for  all  elements 
of  the  field,  maintaining  a count  of  the 
number  of  elements  processed.  Finally,  the 
routine  copies  the  input  data  to  a temporary 
storage  area  for  the  user  to  process 
against, 

e.  Format  Screen 

This  routine,  unless  running  from  a 
typewriter  with  the  verify  option  equal  to 
no,  formats  and  displays  the  status  of  the 
data  most  recently  referenced  by  him.  It 
first  constructs  a heading,  composed  of  the 
record  hey,  data  base  name,  field  name  and 
element  count.  It  then  proceeds  to  fill  the 
remainder  of  the  screen  with  data  beginning 
at  the  element  indicated  by  the  calling 
routine.  If  the  element  length  is  less  than 
the  length  of  the  data  portion  of  the  line, 
the  element  is  written  on  a single  line 
preceedsd  by  the  element  number.  If  the 
element  is  too  large,  the  first  line  is 
processed  as  above,  but  the  remaining  data  is 
split  across  succeeding  lines. 

f.  Ee-prorapt 

This  routine  prompts  the  user  for  his  next 
request.  It  extracts  the  command  heyword, 
and  if  valid,  calls  the  appropriate  calling 
routine.  If  any  type  of  error  is 
encountered,  the  routine  re- prompts  for  the 
correct  information, 

g.  Add  Routine 

This  routine  takes  the  input  data  and  uses  it 
to  create  a new  element  for  the  field  being 
processed.  If  FIELD  is  key  field,  then  new 
record  is  created.  If  there  is  no  data 
entered,  or  if  tie  maximum  allowable  number 
of  elements  has  been  reached,  a diagnostic  is 
written  and  processing  bypassed.  After 
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processing,  that  data  control  is  passed  to 
Eormat  Screen  to  display  the  updated  data, 

h,  Eeplace  Soutine 

This  routine  expects  four  parameters  to  be 
entered,  a starting  point,  ending  point,  old 
data  value  and  a new  data  value.  The 
starting  and  ending  points  are  expressed  in 
terms  of  element  numbers.  If  the  element 
numbers  are  invalid,  or  if  no  old  data  value 
is  entered,  a diagnostic  is  written  and 
processing  bypassed.  The  data  is  then 
searched,  character  by  character,  from  the 
starting  point  to  the  ending  point.  If  any 
occurrence  of  the  old  data  value  is  found, 
it  is  replaced  by  the  new  data  value.  If  no 
occurrence  of  the  old  data  value  was  found,  a 
diagnostic  is  written.  Otherwise,  control  is 
passed  to  Eormat  Screen  to  display  the 
updated  data. 

i.  Cancel  Boutine. 

This  routine  re- initializes  the  data  in  the 
field  to  its  initial  status  when  read  from 
^he  data  base.  Control  is  then  passed  to 
Eormat  Screen, 

i.  Page  Boutine 

This  routine  expects  one  parameter,  which  it 
uses  to  adjust  the  current  element  pointers 
to  adjust  the  segment  of  the  data  which  is 
displayed  on  the  screen.  The  parameter  may 
be  a default  for  forward  paging,  a *B*  for 
backward  paging,  a number  for  a specific 
element  number.  If  the  data  is  invalid  or 
the  reguest  cannot  be  honored,  a diagnostic 
is  written  and  processing  bypassed. 
Otherwise,  control  is  transferred  to  Eormat 
Screen  to  display  the  data. 

k,  "Verify  Boutine 

This  routine  sets  the  switch  that  determines 
whether  the  %iser,  operating  from  a- 
typewriter,  receives  a verification  display 
of  the  data  following  each  command.  The  data 
entered  should  be  'YES*  for  verification  or 
*K0*  for  none.  If  the  data  is  invalid,  a 
diagnostic  is  written  and  processing 
bypassed.  Otherwise,  control  passes  to 
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Icrmat  screen, 

l.  Dele-te  Bontine 

If  the  field  is  to  be  deleted,  it  is  done  and 
control  passed  to  Fermat  Screen.  If  the 
record  is  to  be  deleted,  it  is  done  and 
control  passed  to  End  Eontine.  If  elements 
are  to  be  deleted,  the  routine  will  accept  a 
list  of  elements  or  element  ranges  as  input, 
lor  each,  it  analyses  the  element  number  to 
determine  its  validity.  An  invalid  element 
will  cause  a diagnostic  to  be  written  and 
further  processing  bypassed. 

m.  Insert  Boutine 

Ihis  routine  allows  the  user  to  specify  the 
fields  of  subfile  records  to  be  inserted  into 
the  data  base.  If  no  field  is  specified,  a 
diagnostic  is  written  and  processing  is 
bypassed.  If  the  previous  field’s  data  has 
been  changed.  Output  Boutine  is  called  to 
create  the  necessary  transactions.  Control 
is  then  passed  to  the  Correct  Boutine  for 
further  processing. 

n.  Correct  Boutine 

Ihis  routine  allows  the  user  to  specify  the 
Tcey  of  a new  record  to  be  processed,  the  name 
of  the  next  field  to  be  processed,  or  both. 
If  the  previous  field’s  data  has  been 
changed.  Output  Boutine  is  called  to  create 
the  necessary  transactions.  The  routine 
first  checks  for  a signed  numeric  value  in 
the  key  operand,  and  if  found,  reads  the  file 
sequentially  forward  or  backward  to  the 
desired  record.  If  seguential  processing  is 
not  indicated,  the  routine  extracts  the  new 
key  and  the  new  field  name,  if  present,  and 
transfers  control  to  Get  Becord  for  further 
processing, 

o.  Fields  Boutine  - CAIl  BBFIDS 

This  routine  displays  a list  of  the  field 
names  for  the  data  base  for  the  user.  It 
calls  DBFXDS  to  extract  the  field  names, . It 
also  checks  each  field  until  it  has 
identified  the  key  field,  whose  name  it 
maintains  separately.  It  then  moves  the 
field  names  into  the  output  area,  fitting  as 
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Tcany  as  jpossibla  on  each  line,  and  displays 
them  ~to  the  user.  If  more  names  exist  than 
may  be  displayed  on  the  screen  at  once,  the 
routine  prompts  the  user  for  a decision  as  to 
whether  he  wants  to  see  the  remaining  names 
or  to  continue  correcting. 

p«  Output  Routine 

This  routine  analyses  the  data  maintained  for 
the  field  being  processed,  and  for  each 
element  whose  data  has  been  changed,  creates 
transactions  to  represent  the  change.  The 
routine  calls  Write  Tranplx  to  actually  write 
the  transactions.  The  routine  handles  three 
cases,  an  added  element,  deleted  element  and 
a changed  element.  Upon  completion,  the 
routine  returns  to  its  caller. 

g.  Write  Tranplx 

This  routine  performs  the  actual  creation  of 
transactions,  based  upon  the  data  supplied  to 
it.  If  the  user  is  correcting  the 
transaction  data  base  itself,  the  routine 
updates  the  data  directly,  otherwise  it 

generates  transactions.  If  any  DBPSC  errors 
are  encountered,  this  routine  calls  End 
Routine;  otherwise,  it  returns  to  its 

caller, 

r,  Ind  Routine 

This  routine  processes  any  transactions 

remaining  to  be  written.  It  closes  all  of 
the  files,  -resets  switches,  restores  the 
NASIS  status  to  what  it  was  when  the  program 
was  invoiced  and  returns  to  the  calling 
program. 

CODING  SPECIEICATIONS 

1,  Source  language 

The  correct  command  program  employs  the  IBM  PL/I 
programming  language.  The  special  extensions  of 
that  language,  called  DBPL/I  and  TSPL/I,-  are 
utilized  for  all  access  to  files  in  the  data  base 
and  for  all  terminal  communication, 
respectively, 

2,  Suggestions  and  Technigues 
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Not:  Applicable 


\jL 


Figure  2.  - Top  level  flov/chart. 


WRITE- 

TRANPLX 
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TOPIC  D.4  - HAIBLIIIE  KAIUTENANCE  INVOCATION 


A,  NODDLE  NAME 

Mainline  - Maintenance  Invocation 
Program-ID  - EDBCIMN 
MoaulS'-ID  - DBCLMN 

B*  ANALYST 

Eichard  D«  Graven 
Neoterics,  Inc, 

C,  NODDLE  FUNCTION 

The  maintenance  is  always  run  in  a batch  mode,  A data 
set  mnst  be  created  to  execute.  This  program 

accomplishes  the  creation  of  the  required  data  set, 

D,  DATA  SEQDIBEMENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  data  base  descriptor  file  (defined 

elsewhere) . 

3,  Output  Data  Sets 

a.  Output  files 

The  output  file  is  a line  data  set  whose  name 
is  CXDBMAIN./P1EX$$/.  Where  P1EX$$  is  the 
data  base  name.  It  is  a VISAS  data  set 
EKP=4,  1EECL=132,  KEYLEN=7,  EECFM=V.  It 
contains  the  necessary  TSS  commands  to  run 
maintenance  in  batch. 

b.  On-line  Terminal  Displays 
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Hot  Applicable 
c,  Eorraatted  Print'-outs 
Hot  Applicable 
4,  Beference  tables 
Not  Applicable 
PBOCESSING  SEQUIREHENtS 

1.  Top  Leirel  Flowchart 
See  Figure  2 

2,  Narrative 

This  nsoaul'6  accepts  the  data  base  name  as  a 
parameter.  The  execution  of  this  module  proceeds 
as  follows: 

a.  Write  output  liue  data  set  consisting  of: 

• 1.  EBASE  CIDEBAIH. ’FIIEHAHE* 

2,  lOGOH  ONNEB-ID<TSS-ID) 

3,  CALL  RDBKNTN,«F1IEHAHE* 

4,  LOGOFF 

b.  Close  files  and  guit. 

CODING  SPECIFICATICHS 

1.  Source  Language 
TSS  PL/I, 

2.  , Suggestions  and  Techniques 

Not  Applicable 


Figure  2*  Top  Level  Flowchart 


\J_ 
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TOPIC  D.5  HAIHTENAHCE  DIHECTOB 


a.  MODOIE  KA19E 

Program-ID  - BPBMAIN 
Hodul9«ID  - DBHAIB 

B.  ABALYST 

John  A.  Lo^an 
Heotexics,  Inc* 

C.  HODULE  FUHCTION 

This,  modale  serves  as  the  initializer  and  command 
director  for  fhe  maintenance  sub-system.  It  prompts 
the  user  for  the  file  name  and  invokes  the  maintenance 
function  re guested, 

D.  DATA  REQUIBEBEWTS 

1,  I/O  Block  Diagram 
see  Figure  1 

2.  Input  Data  Sets 

a*  Parameter  Cards 
Kot  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  module  opens  the  file  specified  by  the 
user  for  update,  for  those  modules  which 
require  it, 

d.  . On-line  terminal  Entries, 

The  program  initially  prompts  the  user  for 
the  name  of  the  file  to  be  maintained. 
Subsequently,  the  program  prompts  the  user 
for  his  maintenance  commands. 


3,  Output  Data  Sets 
a.  Output  Files 
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Net  Applicable 

b-.  On-line  Terminal  Displays. 

The  program  displays  various  diagnostic 

messages  to  the  user. 

c.  Jormatted  Print-outs 
Not  Applicable 

d.  Punched  Card  Output  Piles 
Not  Applicable 

4,  Beference  Tables 

The  following  tables  are  referenced  by  the 

program, 

USEBTAB 

7EBETAE 

riDTAB 

PBOCESSIHG  EEQDIBEHENTS 

1.  Top  Level  Flowchart 
See  Figure  2 

2.  Narrative 

Dpon  entry,  the  program  establishes  control  of 
attention  interrupts  and  initiali-zes  terminal 
support.  It  then  prompts  for  the  file  name. , If  a 
. null  value  is  returned,  the  program  is  terminated. 
Otherwise,  the  name  is  validated  and  the  strategy 
is  posted.  If  the  name  is  invalid  the  user  is 
reprompted  for  a valid  file  name. 

The  program  then  allocates  and  initializes  its 
verb  table,  including  any  user  defined  commands. 
Next,  the  program  prompts  the  user  for  a 
maintenance  command.  If  the  command  is  not  valid 
a diagnostic  message  is  issued  and  the  user  is 
reprompted  for  the  maintenance  command.  Five 
successive  invalid  commands  cause  the  program  to 
be  terminated. 

If  the  command  entered  was  COBEECT  or  UPDATE,  the 
file  specified  is  opened  for  update  and  FLDTAB  is 
initialized.  Otherwise,  the  file  name  is  posted 
in  the  HFCB  named  PLEX,  The  entry  point 
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specified  for  the  command  is  then  called  to  effect 
the  processing  requested.  Upon  return,  the 
program  prompts  for  the  next  maintenance 
command. 

When  an  EUD  command,  is  entered,  the  program  closes 
the  file,  releases  ?EEBT5B  and  returns, 

CODIBG  SPECIPICflTlOSS 

1.  Source  language 

The  module  is  T<ritten  using  the  TSS  360  PL/I 
language, 

2,  Suggestions  and  techniques 
Mot  fipplicahle 
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TOPIC  P.6  - HAINTENANCE  lOAD/CEEATI 


A.  MODULE  MAMI 

Load/Create 
Program-ID  - BDBLOAD 
ModTlle-ID  - DBX'OAD 

B,  ANALYST 

Eichard  D.  Graven 
Neoterics,  Inc, 

C,  MODULE  EDNCTION 

This  module  provides  a generalized  file  loading 
capability  for  NASIS, 

D.  ' DATA  BEQUIEIHENTS 

1,  I/O  ElocK  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  PuncEed  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

1.  Ihe  primary  input  file  is  the  data  set 

containing  the  records  to  be  loaded  to 
the  data  base.  This  file  may  be 

indexed,  with  the  keys  having  the  same 
format  and  value  as  that  of  the  final 
data  base,  or  sequential. 

2,  The  only  other  input  file  is  the 

descriptor  data  set  for  the  data  base 
being  loaded, 

d.  On-line  Terminal  Entries 

The  parameters  required  by  the  program  must 
be  entered  with  the  command,  or  default 

values  will  be  assumed. 
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3,  Outpti±  Data  Sets 

a.  Oatpiit  Files 

1.  Ihe  primary  output  file  is  the  data  base 
\{hich  is  being  loaded^ 

2,  The  other  output  file  is  the  error  file, 

on  which  is  written  exact  duplicates  of 
any  input  records  that  cannot  be 

successfully  loaded* . 

b.  On-line  Terminal  Displays 

The  only  output  to  the  terminal  is  the 
informational  and  diagnostic  messages  that 
are  displayed  as  the  program  executes* 

c.  Formatted  Print-outs 
Kot  Applicable 

d.  Punched  Card  output  Files 
Not  Applicable 

4, . Reference  Tables 

The  module  contains  a table  of  error  switches 
which  control  the  action  to  be  taken  for  each 
possible  DEPAC  error;  abend,  skip  record,  or  skip 
field. 

PKOCFSSIHG  BEQUIBEMENTS 
1*  Top  level  Flowchart 
See  Figure  2 
2*  Narrative 

a.  Upon  entry  the  program  establishes  interrupt 
handling  routines  which  will  terminate  if  any 
PI/I  errors  occur,  terminate  if  any  PROfiPT 
errors  occur,  or  display  statistical  data  and 
prompt  the  user  if  an  attention  interrupt 
occurs* 

b.  The  program  next  prompts  for  the  input 
parameters  applying  defaults  for  any 
parameters  that  are  not  entered* 

c. 


The  next  step  is  to  open  the  descriptors  for 
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the  file  specified.  The  file  header  switches 
ate  reset  in  case  the  system  crashed.  The 
index  file  headers  are  read,  and  if  the  field 
is  not  set  for  inversion,  the  loadable  switch 
is  turned  off, 

d.  The  next  function  performed  is  the  definition 
and  opening  of  the  input  file,  the  error  file 
and  the  data  base  itself.  At  this  point,  the 
program  checks  the  user’s  mode  parameter,  and 
if  it  is  restart  passes  control  to  section 
(g)  before  continuing. 

e,  finally,  the  program  is  ready  to  process 

data.  It  reads  an  input  record,  passes  the 
record  to  the  user  written  exit  routine  for 
separation  into  its  component  fields,  Dpon 
return  from  the  exit  routine,  the  program 
tests  the  status  bits,  and  if  set  properly, 
begins  writing  the  input  data  to  the  data 
base,  field  by  field.  If  any  errors  are 

detected,  and  appropriate  diagnostic  is 
written  to  the  user  and  the  action  indicated 
fcy  that  error’s  code  in  the  EEBOE^CODE  table 
is  taken.  The  options  are  to  abend  the 

program,  to  skip  the  remainder  of  the  record, 
or  to  skip  the  field,  When  the  field  has 

been  completely  processed,  the  routine 
continues  with  the  next  input  record,  until 
the  data  is  exhausted, 

f,  Shen  all  of  the  data  has  been  processed  or 

when  a terminal  error  has  been  detected, 

statistical  counts  are  written  on  the  user’s 
terminal  along  with  a termination  message. 
All  of  the  files  are  closed,  and  the  status 
bits  of  the  descriptor  header  records  of  each 
of  the  component  files  of  the  data  base  are 
posted  to  indicate  whether  date  exists  on  the 
file  or  not.  The  program  then  terminates, 

g.  If  the  user  specified  a restart,  the  program 
retrieves  the  last  record  written  to  the  data 
base.  It  then  accesses  the  next  record  to  be 
written  from  the  input  data  set.  Checkpoint 
backup  is  automatically  done  after  every  1000 
records  are  processed,  flhen  the  operation  is 
complete,  processing  continues  with  section 

<e)^ 

CODIMG  SPECIflCSTIONS 


1 


Source  Language 
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This  nodule  should  he  writ-ten  in  the  TSS/360  PL/I 

language. 

Suggestions  and  Techniques 

a.  Eecause  of  the  function  of  this  module, 
extreme  care  should  be  taken  to  code  it  as 
efficiently  yet  as  indestructibly  as 
possible. 

b.  Any  place  in  the  program  where  there  is  any 
remote  possibility  of  an  error,  there  should 
be  a meaningful  diagnostic. 

c.  The  EBEOB^CODES  table  was  designed  to  be  used 
in'  conjunction  with  a ‘ label  array.  The 
digits  in  the  table  are  to  be  converted  to 
index  values  and  an  indexed  branch  taken 
based  onthe  label  array. 

d.  The  user-written  exit  routine  is  responsible 
for  assigning  field  names,  field  off-sets, 
and  field  lengths. 


Figure!.  I/O  Block  diagram 


' V \ 
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TOPIC  D.7  PILE  IHVEETEE 


A.  HOD OLE  SAME 

Haintenanc€  - Tile  Inverter 
Program-ID  - EDBSI7BT 
Module-IB  - DBSIVET 

B.  . ANALYST 

Richard  D.  Graven 
Neoterics^  Inc. 

C.  MODULE  EUNCTION 

The  purpose  of  the  grogram  is  to  take  data  from  certain 
fields  of  a data  tase  and  to  post  this  data  to  an. 
inverted  index  file. 

D.  DATA  REQUIREMENTS 

1.  I/O  Block  Diagram 
See  Eigure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Hot  Applicable 

b.  Punched  Card  Input  Tiles 
Not  Applicable 

c.  Input  Files 

1.  Data  base:  The  primary  input  to  the 

Inversion  module  is  the  file  being 
inverted . 

2.  Data  base  Descriptors;  The  file 
descriptors  are  needed  to  provide 
information. 

3.  Restart  file;  If  the  program  is  invoked 
in  restart  mode,  a restart  file  with 
the  restart  key  is  needed. 

d.  On-Line  Terminal  Entries 


All  of  the  terminal  entries  to  the  Inversion 
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program,  except  one,  are  in  the  form  of 
responses  to  prompting  messages  from  the 
program  itself.  The  exception  is  the  entry 
of  the  initial  command  with  its  parameter  to 
invoke  the  procedure.  The  purpose  of 
terminal  entries  are  to  establish  field 
names,  to  establish  the  mode  of  operation,  to 
establish  number  of  records  to  process,  and 
to  establish  range  of  keys  to  process. 

Output  Data  Sets 

a.  Output  files 

1,  Sortin  file:  This  file  is  • created  by 

the  first  step  and  is  a VSAM  file  with 
the  value  of  the  field  being  inverted 
concatenated  with  the  file  key.  This' 
file  becomes  the  input  for  step  two,  the 
sort, 

2,  Sort out  Pile:  This  file  is  the  sorted 

output  from  step  two,  the  TSS  sort 
utility.  The  file  becomes  the  input  to 
the  third  step, 

3,  Plex  File:  This  file  is  the  output  of 

step  three  in  the  form  of  an  index  file 
with  the  internal  field  value  as  the 
key.  This  file  becomes-the  input  to 
step  four,  the  translation  step, 

*1,  Eange  File:  This  file  is  the  output  of 

step  three  if  field  is  indexed  with 
internal  format,  and  is  the  output  of 
step  four  if  field  is  indexed  with 
external  format.  Eange  of  keys  to 
invert  must  have  been  specified  for  this 
file  to  be  produced.  This  file  becomes 
the  input  to  the  index  merge  program, 

5,  Database  Index  File:  This  is  the  final 

index  file.  It  is  the  output  of  step 
three  if  field  is  indexed  with  internal 
format,  and  is  the  output  of  step  four, 
if  field  is  indexed  with  external 
format, 

b,  On-Line  Terminal  Displays 

All  on-line  terminal  displays  for  the 
Inversion  program  follow  the  same  format. 
The  TSPL/I  facility  of  the  system  is  utilized 
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to  reguest  entires  at  a terminal  and  display 
progress  ‘ijiformation, 

c,  Ecrmatted  Print-Outs 
Eot  Applicable 

d.  Punched  Card  Output  Piles 
Kot  Applicable 

4,  Reference  Tables 

Not  Applicable 

•E.  PROCESSING  SEQDIBiaPNTS 

1.  Top  Level  flowchart 

See  Figure  2 

2.  Narrative 

a*  Parameter  Prompting  routine 

Prompt  the  user  for  program  parameters. 

Initialise  program  swtiches  and  tables.  Read 
appropriate  field  descriptor  for  each  field 
name,  saving  field  length.  If  applicable, 
fill  external  indexing  table,  inverted  suffix 
table,  and  spanned  table.  If  field  is 

indexed  external,  read  index  file  header 
descriptor  and  get  external  field  length. 
Read  appropriate  region  descriptor  and  save 
the  file  hey  length  and  key  name.  Check  the 
operating  mode  and  go  to  appropriate 
section, 

b.  Field  stripping  routine  (step  one) 

Loop  through  fieldname  table  and  DDEF  the 
sortin  files,  DDEF  the  restart  file.  If 

restart  run,  read  in  restart  key  and  read 

this  file  record.  If  range  run,  read  first 
file  key  to  start  at.  Read  sequentially  the 
input  file,  save  the  internal  file  key.  Loop 
through  the  index  file  suffixes.  Loop 

through  the  field  name  table.  Loop  through 
the  #FIELD  for  this  field,  Write  out  a 
sortin  file  record.  If  end  of  file  reached, 
go  to  next  section.  If  end  range  key  reached 
go  to  .next  section.  If  number  of  records  to 
process  is  reached,  write  out  restart  file 
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and  terminate. 

c.  Sort  step  (step  two) 

EDI'P  the  sortin  file,  sortout  file  and  invoice 
the  ISS  sort  utility , 

d.  Write  VISAS  file  (step  three) 

lind  the  Jcey  length  of  the  VISAS  output  file, 
Ihis  will  be  the  maximum  length  -of  the  fields 
being  inverted  on  the  same  index  file.  If 
field  is  indexed  external,  use  external 
length.  If  index  file  is  spanned,  increase 
by  one.  If  external  indexing,  IDEE  the 
output  file  as  ’PLEX.*,  if  range  keys  and  no 
external  indexing,  DEEE  output  file  as 

’SANGE. * If  not  a range  run,  and  no  external 
indexing  DDEE  output  file  as  final  index 
ESHAHE.  Bead  input  file.  If  Keys  are  the 
same,  concatenate  file  key  onto  list  of 
keys.  If  list  has  reached  maximum  list 
length,  up  the  span  character  and  initialise 
list  to  null.  If  keys  are  different,  -write 
cut  index  record.  If  end  of  input  file 
reached,  write  out  last  index  record  and 

check  to  see  if  external  indexing.  If 

external  indexing,  proceed  to  next  section. 
Display  record  counts  for  user  and  post  the 
index  file  descriptor  data  bit, 

e.  Translate  Keys  routine 

DDEE  the  input  file  and  the  output  VISAH 

file,  Bead  input  file  sequentially.  Search 
Key  for  first  blank  character  after  first 
non-blank  character.  Use  this  parsed  string 
to  pass  to  field  formatting  routine.  Replace 
internal  value  in  key  with  external  value. 
If  end  of  file  reached,  post  data  bit  in 
index  header  descriptor  record.  If  more 
field  names  in  table,  go  to  sort  step. 
Terminate  the  program. 

CODIEG  SPECIEICATIOHS 

1.  Source  language 

The  Inversion  program  employs  the  IBM  PL/I 
programming  language.  The  special  extensions  of 
that  language,  called  DBPX/I  and  TSPL/I,  are 
utili'zed  for  all  access  to  files  in  the  data  base 
and  for  all  terminal  communication. 
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respectively. 

Suggestions  an!  Techniques 

The  jnolnle  can  very  easily  be  broken  up  into  four 
separate  modules,  step  one  - strips  the  fields 
from  file;  step  two  - the  TSS  sort  step;  step 
three  - the  internal  index  file  creating  step; 
step  four  the  external  or  translation  step* 

This  could  he  a ma-jor  enhancement  for  core 
consideration  and  storage  requirements. 


SORTOUT.j 
FILE  ' 


FIGURE  1.  I/O  BLOCK  DIAGRAM 
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TOPIC  D.8  - DBLOAB  PIIES  BACKUP 
A.  MOBULE  NAHl 

Maintenance  - DBLCAD  Files  Backup 
Program-ID  - EEBLEBK 
Hodule-ID  - DBIDBK 

B«  ANALIST 

EicharU  E,  Graven 
Neoterics,  Inc. 

C,  MODULE  FUNCTION 

This  module  is  a utility  called  by  DBIOAD  to  backup  all 
files  of  a data  base  being  loaded  at  a checkpoint  of 
every  (1,000)  records. 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Kot  Applicable 

b.  Pnched  Card  Input  Files 
Mot  Applicable 

c.  Input  Files 

The  input  files  are  all  files  of  the  data 
base  being  loaded  (such  as  anrhnr. 
associated,  index,  subfile) * 

d.  On-line  Terminal  Entries 
Kot  Applicable 

3.  Output  Data  Sets 
a.  Output  Files 

The  output  files  are  backup  generation  data 
group  (2  levels)  of  all  files  of  the  data 
base  being  loaded.  The  DSNAME  will  be 
CKNEEID. « BACKUP ’.PLEXII  file  suffix. 
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Example: 

SAEETy.EACKDE.COMAT$Y 

b.  On-line  Terminal  Displays 
Hot  Applicable 

c.  formatted  Print-ont 
Hot  Applicable 

d.  PuncKed  Card  Output  Piles 
Hot  Applicable 

4,  Beference  Tables 
Hot  Applicable 
PBOCESSING  BEQUIHEHEHTS 

1.  Top  Level  Flowchart 
Hot  Applicable 

2,  Harrative- 

This  module  is  coded  as  a sub-procedure  to  DBIOA-D. 
It  deals  with  three  parameters: 

a.  The  ownerid  of  the  file, 

b.  The  data  base  name, 

c.  The  character  string  of  f ile ' suffixes. 

The  ownerid  is  a 1-8  character  string  of  the  file 
owner  such  as;  SAFETY 

The  data  Base  name  is  a six  (6)  character  string 
of  the  file  name  padded  with  *$*  such  as; 
COMATS, 

The  string  of  file  suffixes  to  be  backed  up  looks 
like:  * 1,A,B,1,2». 

The  string  of  file  suffixes  is  searched  and 
concatenated  to  the  data  base  name  to  construct 
the  backup  file  DSHAME,  Index  file  A for  the 
COMAT  file  owned  by  the  TSSid  SAFETY  would  be 
backed  up  with  a DSHAME  of  SAFETY, BACKUP, COHATSA 
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Tie  Pl/I  routine  SYSOBP  is  used  to  CATALOG  a level 
2 generation  data  group,  LLIF  the  file,  CDS  the 
file,  and  EELSASE  the  DDKAHE, 

CODING  SPECIFICATIONS 

1.  Source  Language 

PL/I  with  no  EBPL/I  statements, 

2,  Suggestions  and  Technigues 

Depending  on  storage  available  under  a given 
userid,  it  might  be  advantageous  to  copy  the  files 
to  a data  cell  or  private  disc  pack. 


DATAPLEX 


Figure  1.  I/O  Block  diagram 
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TOPIC  D, 9 - DESCBIPTOB  EDITOE  - ADD  - CHANGE  COMHANDS 

A,  HODUIE  NAHE 

Program-ID  - BDBEEAC 
Hodule->Ham€  - DEEIAC 
Entry  Points 

DEEBAC1  - ABB  Cominana 
DBEDAC2  - CHANGE  Command 

E.  ANALYST 

Barry  G,  Hazlett 
Nooterics,  Inc« 

C.  J30DULE  FHNCTION 

Those  commands  allou  the  user  to  create  and  modify 
field  descriptors. 

D.  BATA  BEQDIBEHENTS 

1.  I/O  Block  Diagram 
See  Eignre  1 

2.  Input  Bata  Sets 
Hot  Applicable 

3.  Output  Data  Sets 

a.  Output  Files 
Hot  Applicable 

b.  On-Line  Terminal  Bisplays 
Not  Applicable 

c»  Formatted  Print-Outs 
Hot  Applicable 

4.  Beference  Tables 

The  fcllo-wing  external  tables  are  referenced  by 
HBEEDAC: 

-1.  El  ELD 

2.  ELB 

3,  ELB  STBING 
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4.  HDB 

5.  • HDE.STRING 

6.  It 

a description  of  these  tables  can  be  fonnd  in  the 
dataset  specifications  of  the  DRB. 

E,  PBOCESSIRG  EIQGIEiaEHTS 

1»  Top  Level  flowchart 

See  Figure  2 

2»  Narrative 

Upon  entry  into  SDEEDfiC  a flag  is  set  to  indicate 
if  the  ADB  or  CHANGE  command  was  entered.  The 
routine  DBEBGF  is  called  to  obtain  a valid 

fieldname.  In  ABB  mode  it  must  be  a valid 
non-existent  and  non-reserved  fieldname.  In 
CHANGE  mode  it  must  be  an  existent  non  reserved 
fieldname  with  the  exception  of  the  fields 
PEEEFORH  and  CONBENTS  and  it  must  not  be  a 
superfield  nor  a subfile  control  field.  If  in 
ABB  mode  a FLE  structure  is  allocated,  initialized 
and'  posted  with  the  fieldname. 

The  user  is  prompted  for  the  field  type  and  the 
input  is  validated.  If  it  is  invalid,  the  user  is 
given  a diagnostic  and  prompted  for  a new  value. 
If  in.  update  mode,  the  user  is  not  allowed  to 
change  the  field  type  if  it  affects  the  field 
length- and  the  field  appears  in  the  fixed  part  of 
the  record.  The  user  is  also  not  allowed  to  make 
the  key  field  a bit  field. 

If  there  is  more  data  in  the  parameter  list  *TYPE* 
the  user  is  prompted  for  an  alignment  value.  If 
it  is  invalid,  the  user  is  given  a diagnostic  and 
prompted  for  a new  value.  If  no  value  is  entered 
a built  in  default  value  is  assumed  and  posted  in 
■PLD. 

The  field  form  is  prompted  for  and  validated.  If 
invalid,  the  user  is  given  a diagnostic  and 
prompted  for  a new  value.  The  anchor  file  key 
field  and  bit  field  can  only  be  of  fixed  form.  In 
Update  mode,  the  user  can  not  change  fixed  field 
to  a varying  or  elemental  field,  the  necessary 
values  are  posted  in  FLB, 

The  user  is  prompted  for  a field  length  and  the 
value  is  validated  against  prestored  maximum 
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values  for  single  and  multielement  fields.  If  it 
is  invalid,  the  user  is  given  a diagnostic  and 
prompted  for  a ne-»  value.  The  correct  values  are 
posted  in  flD, 

If  the  field  is  non-eleraental,  go  prompt  the  user 
for  a conversion  routine,  otherwise  the  user  is 
prompted  for  an  element  length  value  if  necessary. 
For  several  field  types  the  only  element  length 
value  is  posted  in  FID.  If  the  element  value  is 
Invalid,  the  user  is  given  a diagnostic  and 
prompted  for  a new  value. 

The  user  is  prompted  for  the  number  of  elements 
and  the  input  validated.  If  the  value  is  invalid, 
the  user  is  given  a diagnostic  and  prompted  for  a 
new  value.  A correct  value  is  posted  in  FLD.  The 
parameter  unigue  element  is  prompted  for  and 
processed  in  the  same  manner. 

The  routine  IFEDG5  is  called  to  obtain  and  process 
the  conversion,  formatting,  validation  routine 
names  and  validation  argument. 

At  this  point  of  adding  the  hey  field  or  in  update 
mode,  the  rest  of  the  parameters  are  ignored,  in 
update  mode  the  changed  information  is  posted  to 
the  descriptor  dataset  by  calling  DBEDFl,  and  then 
go  save  the  command  string.  The  use  is  prompted 
if  the  field  is  to  be  indexed.  If  the  answer  is 
no  then  go  prompt  the  user  for  associated  file 
information,  otherwise  the  user  is  prompted  as  to 
which  index  file  the  field  is  to  appear.  If  no 
defining  fieldname  is  entered,  a new  index  file  is 
created  for  this  field.  Otherwise  the  field  is 
placed  on  the  same  index  as  that  of  the  defining 
field.  In  the  CHANGE  command,  if  the  field  was 
already  indexed  on  a different  file,  it  must  be 
deleted  from  that  index  file  before  it  is  placed 
on  the  new  index  file. 

The  user  is  prompted  as  to  whether  the  index  key 
is  to  be  in  either  internal  or  external  form.  If 
no  value  is  entered,  internal  is  assumed.  If  the 
value  is  external  then  the  user  is  prompted  for 
and  must  enter  the  maximum  length  of  the  external 
value. 

The  user  is  prompted  if  the  index  is  to  be 
spanned.  If  no  value  is  entered,  it  is  assumed 
not  to  be  spanned.  At  this  point,  the  index  is 
ready  to  be  setup.  If  it  is  a new  index  a header 
descriptor  is  allocated  and  setup  for  the  index. 
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else  the  new  information  is  posted  to  the 
existing  header. 

The  routine  IBED6A  is  called  to  determine  if  the 
field  is  to  he  placed  on  an  associate  file. 

The  user  is  prompted  if  the  field  is  to  he  on  a 
subfile.  If  not  go  prompt  the  user  for  a subfile 
value  as  obtained,  the  subfile  header  is  updated 
accordingly. 

The  user  is  prompted  for  the  defining  base  field 
name  if  the  field  is  to  be  a subfield.  If  no 
value  is  entered,  the  field  will  not  be  a 
subfield.  If  it  is  to  be  a subfield,  the  user  is 
prompted  for  an  offset  value.  If  none  is  entered, 
a value  cf  0 is  assumed.  In  case  the  defining 
base  field  is  either  BECLEN  or  the  anchor  key 
field  the  user  is  prompted  for  the  particular 
file  on  which  this  subfield  is  to  be  placed.  The 
user  can  specify  the  actual  file  name  if  known  or 
indicate  the  type  of  file  on  which  the  subfield  is 
to  be  placed.  If  ASSOCIATE  or  SUBFILE  is 
specified  the  user  is  prompted  for  a field 
defining  which  associate  file  or  which  subfile, 
the  subfield  information  is  posted  in  FLU. 

At  this  point  all  of  the  parameters  have  been 
entered,  processed  and  the  information-  posted.  It 
is  now  determined  which  file  list  the  field  is  to 
be  placed  and  if  not  in  the  proper  place  already, 
threaded  onto  the  end  of  that  file  list. 

If  adding  the  anchor  key  field  then  the  fields 
FIXEKE2,  EEEEFOEK,  and  COMMEHTS  are  setup  on  the 
appropriate  files  and  an  index  file  is  setup  for 
FEBEFOEH, 

The  command  string  is  saved  in  the  current 
strategy  and  control  is  returned  to  the  calling 
routine. 

CODING  SPECIFICATIONS 
1,  Source  language 

PL/I  with  TSEl/I  statements. 

Suggestions  and  Techniques 
Not  Applicable 


2 


rigure  I/O  Block  diagram 


"TT 


Figure  2a.  Top  level  flowchart 


Figure  2b . Top  level  flowchart 
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TOPIC  E,  10  “ DESCBIPTOR  EDITOB  - ADDLIKE  - EENAHB  COMMANDS 

A.  MODULE  NAME 

Program-ID  - BDBEBAB 
Module-ir  - DBTDAB 
Entry  Points: 

DBEDAE1  - ADDIIKE  Ccmmand 
DBEDAB2  - BENAKE  Coffliaand 

B.  - AHALTST 

Barry  G.  Ha^lett 
Neoterics,  Inc, 

C.  MODULE  TUNCTION 

The  ADDIIKE  command  creates  a new  field  descriptor 
exactly  liXe  an  existing  descriptor  witL  a different 
name.  The  RENAME  command  changers  the  name  of  an 
existing  descriptor, 

D.  DATA  BEQUIBEMENTS 

1,  I/O  Block  Diagram 
See  figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Hot  Applicable 

c.  Input  Files 
Not  Applicable 

3,  Output  Data  Sets 

a.  Output  Biles 
Not  Applicable 

b.  On-line  Terminal  Displays 
Not  Applicable 
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c.  lormattcS  Print-outs 
Not  Applicable 
4,  Beference  Tables 

The  following  external  tables  are  referenced  by 
EDBEDAB;. 

JIELD 
ELD 

ELD^STEIHG 
HDE^ 

SECUBITY 
SUPER 
SUPEB_SIB 
SUPEB_STE 
EAIID 
X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DWB, 

PROCESSING  BEQUIBEMENTS 

1.  Top  Level  Elowchart 
See  figure  2 

2.  Narrative 

The  entry  points  are  ADDLIKE  command  - DBEDAHI  and 
EENAHE  command  - DBEDAB2.  Upon  entry  into  either 
command  a flag  is  set  indicating  which  command  was 
called.  After  which  the  two  commands  share  common 
code  for  parameter  processing. 

Boutine  DBEDGf  is  called  to  obtain  a valid  new 
field  name.  To  be  valid  the  new  field  name  must 
be  of  alphanumeric  of  at  most  eight  characters 
long,  must  not  already  exist  and  must  not  be  a 
reserved  field  name. 

Boutine  DBEDGf  is  called  to  obtain  a valid 
existing  fieldname.  This  field  must  exist  and 
must  not  appear  in  the  reserved  fieldname  list. 

If  in  the  SESAME  command,  then  the  name  of  the 
specified  existing  field  is  changed  to  the 

specified  new  field  name  and  the  field  name  change 
is  posted  in  the  FIELD  structure.*  At  this  point 
the  command  string  is  stored  in  the  current 
strategy  and  then  control  is  returned  to  the 
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calling  routine. 

If  in  the  AIIIIKl  command  the  existing  field  is 
duplicated,  the  new  fieldname  posted  in  the  copy. 
The  new  fieldname  is  posted  in  the  FIELD 
structure.  The  ADDIIKE  command  string  is  saved 
in  the  current  strategy,  after  which  control  is 
returned  to  the  calling  routine, 

‘ CODING  SPECXIICATIOBS 

1.  source  Language 

PL/I  with  TSPL/I  statements. 

Suggestions  and  Techniques 

Not  Applicable 


2 


Figure  1 . I/O  Block  Diagram 


H'  I 


Figure  2.  Top  Level  Flowchart 


\ 
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TOPIC  D.11  - DESCRIPTCB  EDITOR  - CHKPOINT  COHHSED 

A.  MODDLE  NAME 

Program-ID  - EEBEECP 
Sodule-ID  - DBEECP 

B.  ANALYST 

Barry  G.  Ha-zlett 
Neoterics,  lac. 

C.  MODULE  EUNCTIOHS 

This  commana  is  ased  to  save  the  descriptor  tables  as 
they  exist  ia  meracry  ia  a VSAM  data  set  as  that  they 
may  be  retrieved  at  a fatare  time  by  ase  of  the  BESTOEE 
command  and  then  continae  to  create  the  descriptors 
from  that  point. 

1..  I/O  Blcclc  Diagram 

See  Figure  1 

2.  Inpat  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Panched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Not  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 

The  output  file  is  a TSS  VSAM  data  set  named 
DESCSP.CHKPCIKT.  Refer  to  the  data  set 
specifications  for  a description  of  this  data 
set. 

b.  On-line  Terminal  Displays 
Not  Applicable 


c 


Formatted  Print-Outs 
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Not  Applicable 
4,  Reference  Tables 

The  following  external  tables  are  referenced  by 
SD3EDCP; 

1.  EIILD 

2.  ELD 

3.  ELD_STEING 

4 . HDB~ 

5.  HDB  STBIH6 

6.  EECSEC_STE 

7.  SECDEXTY^STB 

8.  ■supIe_str 

S.  VALID 

10,  -x 

The  descripticn  of  these  tables  is  specifications 
in  the  dataset  of  the  DEB. 

PROCESSING  EEQUIBEHENTS 

1,  . Top  Level  Flowchart 

See  Figure  2 

2.  Narrative 

Upon  entry  into  CHKPOINT,  any  previously  existing 
checkpoint  dataset  is  erased  by  use  of  ASHEESE 
routine.  The  data  set  record  length  is 
dynamically  determined  by  calculating  the  length 
of  that  part  of  the  X structure  that  • oust  be 
saved,  the  current  length  of  the  FIELD  structure 
and  using  the  larger  of  the  two  values. 

The  data  set  CHKPOINT. DATASET  is  created  and 
initialized  by  use  of  the  routine  ASSDCB  to 
create  the  ECE  for  the  data  set,  routine  ASMDD  to 
data  def  the  dataset  routine  ASMENDS  to 

initialize  the  JECB,  and  routine  ASMOPEN  to  open 
the  checkpoint  data  set. 

The  variable  part  of  the  X structure  is  pat  into 
the  data  set  by  use  of  the  ASMPUT  routine,  and 
likewise  the  FIELD  structure. 

Each  of  the  fields  are  saved  through  use  of  ASMPOT 
routine  by  creating  the  following  character 
string;  the  FID^STEISG  concatenated  to  SUPEE_STB 
if  it  is  a superfield,  concatenated  to 

SECDEITY^STE  if  there  is  field  security  on  this 
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field,  concatenated  to  VALID. A EGO HE NT  if  the  field 
has  a validation  argument. 

Each  of  ±he  headers  are  saved  through  use  of 
ASHPOT  routine  by  creating  the  following 
character  string;  the  HDE^STRING  concatenated  to 
RECSEC_STE  if  the  file  has  record  security. 

The  checkpoint  dataset  is  closed  by  use  of  the 
routine  ASHCLOS,  after  which  control  is  returned 
to  the  calling  routine, 

CODING  SPECIFICATICNS 

1,  Source  Language 

PL/I  with  T?SP1/I  statements. 

Suggestions  and  Techniques 

Not  Applicable 


2 


Figure  2_.  Top  level  flowchart 
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TOPIC  D.12  - DESCHIPTOB  EDITOE  - CEEAT  SUB  COHHAHD 

A.  . MODULE  HAME 

Program-ID  - EDBIICS 
Module-ID  - DBEDCS 

B,  ANALYST 

Barry  G,  Hazlett 
Neoterics,  luc, 

C«  MODULE  FUNCTION 

This  routine  is  used  to  define  and  setup  the  necessary 
field  tc  create  a subfile, 

D.  DATA  EEQUISIHENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Piles 
Not  Applicable 

3,  Output  Data  Sets 
a,  'Output  Piles 

Not  Applicable 

b«  On-Line  Terminal  Displays 
Not  Applicable 
c.  Formatted  Print-Outs 
Not  Applicable 

4,  Beference  Tables  — 
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'The  following  external  tables  are  referenced  by 
RDEEDCS: 

FIEID 
FID 

FIB  STRING 

hde" 

HDE^STBING 
X 

A description  of  these  tables  can  be  found  in  the 
dataset  specif icaticns  of  the  DWB, 

PROCESSING  EEQDIRE0EHTS 

1.  Top  Level  Flowchart 
See  Fignre  2 

2,  Narrative 

Upon  entry  into  CEEATSOB,  module  DBEDGF  is  called 
to  obtain  a valid  subfile  control  fieldname.  To 
be  valid  this  field  name  must  not  be  longer  than 
six  characters  long  and  be  a valid  alphanumeric 
character  string.  The  following  field  names  are 
then  created.  The  subfile  key  field  name,  the 
subfile  parent  hey  field  name,  and  the  subfile 
record  security  field  name.  Of  the  above 
mentioned  four  fieldnames,  none  must  exist  and 
none  must  be  a reserved  field  name  for  the  entered 
subfile  control  field  name  to  be  valid. 

The  user  is  prompted  for  the  maximum  number  of 
subfile  records  per  anchor  file  record  that  may 
be  loaded  ante  the  subfile.  The  number  must  be 
less  than  or  equal  to  1325,  If  the  number  is 
valid,  processing  continues,  else  the  user  is 
given  a diagnostic  and  prompted  for  a new  number. 
This  number  then  becomes  the  number  of  elements  on 
the  subfile  control  field. 

Routine  BBEDGA  is  called  to  determine  if  the 
subfile  control  field  is  to  appear  on  an  associate 
file. 

The  subfile  control  field,  the  subfile  hey  field, 
and  the  subfile  parent  key  field  are  now  created 
and  posted  with  the  proper  values.  The  subfile 
control  field  is  placed  in  the  varying  field  list 
of  either  the  anchor  file  or  the  appropriate 
associated  file.  The  subfile  key  field  and  the 
parent  field  are  placed  in  the  fixed  list  of  the 


1. 

2, 

3, 

4. 

5. 

6, 
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appropriate  suifile. 

The  afore  mentiorea  field  names  are  placed  in  the 
reserved  field  name  list.  The  command  string  is 
saved  in  the  current  strategy,  after  which  control 
is  returned  to  the  calling  routine. 

CODING  SPECIPICfiTIONS 

1.,  Source  language 

PL/X  with  TSPl/I  statements.  . 

Suggestions  and  Techniques 

Hct  Applicable 


2 


TESoNAir^ 

^ 

p'H'C'P'npc 

DESCRIPTOR 

JKJLJiDriJJLib 

TABLES 

Figure  1. 


I/O  Block  diagram 


li- 


/ 
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TOPIC  D.13  - DESCSIPTCB  EDITOB  --  END  COHEANDS 

■A.  MODULE  NAME 

Program-I-D  - BDBEDDE 
Modale-ID  - DBEDDE 

-B.  ANALYST 

Barry  G»  Hazlet.t 
Neoterics,  Inc, 

C,  MODULE  EUNCTION 

This  module  is  the  entry  point  into  the  Descriptor 
Editor,  It  prompts  for  and  processes  Descriptor  Editor 
commands  and  calls  the  appropriate  command  routine. 
The  END  command  is  used  to  terminate  Descriptor  Editor 
processing  and  return  control  to  the  maintainence 
director, 

D.  DATA  BEQUIBEHENTS 

1,  I/O  Block  Diagram 
See  Eigure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Hot  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-Line  Terminal  Displays 
Not  A^pplicable 

c.  Formatted  Print- outs 
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Sot  Applicable 
4,  Seference  Tables 

The  fcllo-wiug  external  tables  are  referenced  by 
EDEIDr-Z: 

1.  FIEID 

2.  X 

3.  VEBBTAB 

A descripticn  of  these  tables  is  found  in  the 
dataset  specifications  of  the  DWB. 

E.  PEOCESSISG  EEQUIEEHESTS 
1.  Top  level  riOTschart 

See  Figure  2 
2*  Narrative 

Hodule  DBEDIN  is  called  to  set  up  mode  of 
operation  and  all  of  the  tables  necessary  to  the 
running  of  the  descriptor  editor* 

The  user  is  prompted  for  his  next  Descriptor 
Editor  command.  If  the  command  is  invalid  as 
determined  by  a search  of  the  verb  table,  the  user 
is  given  a diagnostic  and  prompted  for  a command 
string. 

If  the  command  is  not  END,  then  the  appropriate 
command  is  called  by  use  of  the  CALL  routine  when 
control  is  returned,  the  user  is  prompted  for  his 
next  command. 

If  the  command  is  END  then  if  the  user  has  not 
filed  his  corrections,  additions,  or  changes,  he 
is  prompted  informing  him  such  and  asked  if  he 
really  wants  to  terminate  the  Descriptor  Editor. 
If  the  anser  is  no  then  the  user  is  prompted  for 
his  next  Descriptor  Editor  command,  else  the 
Descriptor  Editor  run  is  terminated. 

At  termination  each  field  storage  and  each  header 
storage  area  is  released.  The  FIELD  and  X 
structures  are  then  released.  Control  is  then 
returned  to  the  calling  routine. 

F.  CODING  SPECIFICATIONS 


1 


Source  Language 


PL/I  uith  DBPI/T  and  ISPL/I  statements. 
Suggestions  and  lechnigues 
Not  Applicable 


Figure  1.  I/O  Block  diagram 


V 


INITIALIZE 

DBEDIN 


Figure  2,  Top  level  flowchart 
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TOPIC  D,14  - DESCEIPTCS  EDITOH  - DISPIAT  INTESNAL  COHMAUP 


A.  , MODULE  NAME 

Program-ID  - RDBEEDI 
Module-ID  - DBEDDI 

B.  ANALYST 

Barry  G*  Hazlett 
Neoterics,  Inc. 

C.  MODULE  EUNCTION 

This  moSuls  is  a debugging  tool  used  to  display  the 
various  external  descriptor  tables  (DESCTAB) , by  their 
internal  name,  field  descriptors  by  their  field  name 
and  header  descriptors  by  their  file  ids. 

DISPL AYI  DISTYPE=<I ,F , H> , DISNA ME=structure-nam e 

where; 

DISTYPE  is  the  type  of  variable  to  be  displayed  I for 
internal,  F for  field  descriptor  and  H for  file  or 
header  descriptor. 

DISNAME  is  the  name  of  the  variable  to  be  displayed. 
For  internal  mode  the  following  structures  may  be 
displayed. 

EBROBFILE 

FIELD 

FLD 

BDR 

RECSEC 

SECURITY 

SUPER 

VALID 

IID^COM BENTS 

fidIfreefcbm 

FLD  RS 

fldIsdbcntel 

FLD_SUBID 

FLD_SDBEK 

hdeIassoc 

bdr'index 

INIT^FLB 
INIT^HDB 
IHIT_RECSEC 
INIT_SECURITY 
INIT  SUPER 
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10  ElB 

ioIhde 

IO_HECSEC 

to^sectjeity 

Elix 

EESEEVEC 

XS 

X 

Eor  fielS  mode  the  name  of  the  field  to  be 
displayed  is  supplied,  Por  header  mode  the  file 
suffix  id  is  entered, 

D. . DATA  EEQUIEEBEKTS 

1,  I/O  Block  Diagram 
See  Eigure  1 

2,  Input  Bata  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Sot  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 
Set  Applicable 

b.  On-Line  Terminal  Displays 
Sot  Applicable 

c.  Formatted  Print-Outs 
Sot  Applicable 

4,  Beference  Tables 


1.  FIELD 

2.  ELD 

3.  HDB 
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4. , EECSEC 
5.  SECOBITY 
'6,  SUPEB 
-7.  VALID 
8.  X 

A descripticn  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DWE. 

PEOCBSSING  EEQUIEEHENTS 

•1 , lop  Level  PloTichart 

See  Figure  2 

2*  . Narrative 

Upon  entry  into  EDBEDDI  the  user  is  prompted  for 
the  display  type.  If  the  display  type  value  is 
not  *1«,  *P*,  or  *H*  the  user  is  given  a 
diagnostic  and  prompted  for  a nev  value. 

Depending  on  the  display  type  the  user  is  prompted 
for  either  an  internal  structure  name,  a field 
name,  or  a header  id.  If  the  internal  structure 
name  is  not  contained  in  the  list  of  names  in  the 
module  function  section,  or  the  field  does  not 
exist  or  the  file  does  not  exist,  the  user  is 
given  a diagnostic  and  prompted  for  a new  display 
name  value. 

Uhen  displaying  an  internal  name,  a label  variable 
is  used,  one  label  for  each  structure  that  may  be 
displayed.  At  each  of  these  pieces  of  code,  a 
generalized  display  subroutine  is  called  to 

display  the  desired  type  of  structure  passing  the 
address  of  the  particular  structure  to  be 
displayed.  This  is  done  for  all.  structures  except 
for  the  structures  FLEX,  EREOBFILE,  and  XS.  A 
word  about  these  display  procedures  later.  The 
information  from  the  structures  PLSX  and 

EBBOEFILE  is  setup  and  displayed.  The  display  of 
the  X structure  is  a service  of  calls  to  the 
different  display  procedures,  one  for  each  minor 
structure  of  X to  be  displayed. 

When  displaying  a field  descriptor,  a call  to  the 
procedure  DIS^FLD  is  called  to  display  the  proper 
FLD  structure.  If  the  field  is  a superfield,  has 
a validation  argument,  or  has  field  security, 
calls  are  made  to  the  routines  DIS  SUPEE, 
DIS_VALID,  and  DIS_SECUEITY  to  display  the”proper 
structures.  This  is  done  to  display  all  of  the 
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inforTEation  associa-ted  with  the  field. 

When  display  a header  descriptor,  a call  is  made 
to  BIS^HDR  to  display  the  proper  HDB  structure  and 
if  the  file  has  record  security,  a call  is  made  to 
DIS^EECSIC  to  display  the  appropriate  record 
security  information. 

After  the  information  has  been  displayed,  control 
is  returned  to  the  calling  routine. 

Tor  displaying  the  actual  desired  data  several 
internal  procedures  are  set  up,  one  for  each  type 
of  structure.  They  axe  DIS_F1ELI),  DIS_ELD, 
DIS_HBE,  DIS_EECSEC,  DIS_EESEEVED,  DIS_SECUilTY, 
DIS^SUPES,  BIS^VALID,  and  DIS_XS.  These 

procedures  build  the  output  information  in  a work 
area  in  predefined  formats.  The  information  is 
output  to  the  terminal  thru  use  of  the  TS  PEOHPT 
facility.  The  output  consists  of  a title  line 
followed  by  the  data  usually  displayed  beneath  the 
title  line. 

CODING  SPECIFICATIONS 

1,  Source  Language 

PI/I  with  TSPI-/I  and  BBPI/I  statements. 

Suggestions  and  Techniques 

Hot  Applicable 


2 


Figure  1,  I/O  Block  diagram 


DBEDDI 


Figure  2a*  Top  level  flowchart 


Figure  2b*  Top  level  flowchart 
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TOPIC  D^15  - DESCEIPTCE  IDITOE  - DEIETE  FIELD  COHMAND 

A.  HOD OLE  EAHE 

Program-ID  - EDBBDDL 
Hodule-ID  - DBEDDL 

B.  ANALYST 

Barry  G,  Hazlett 
Neoterics,  Iiic* 

C.  HODOLE  FUNCTION 

This  module  is  used  to  delete  a previously  defined 
field  descriptor. 

D.  DATA  EEQUIFEHENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 
Not  Applicable 

3.  Output:  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-line  Terminal  Displays 
Not  Applicable 

c.  Formatted  Print-Outj 
Not  Applicable 

4,  Eeference  Tables 

The  following  external  tables  are  referenced  by 
EDBEDDI. 

1.  FIELD 

2,  FLD 
• 3,  HDE 

4,  SDPEB 

5.  X 
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A description  of  these  tables  is  found  in  the 
dataset  specif icaficns  of  the  DWB, 

E,  PBOCESSING  EEQOIBE BENTS 

1 • lop  Level  Elowchart 

See  figure  2 

2.  Narrative 

Routine  EBSDGE  is  called  to  obtain  a valid 
fieldname.  To  be  valid,  the  field  mast  exist.  If 
the  field  name  appears  in  the  reserved  list,  then 
it  must  be  a subfile  control  field  and  there  must 
be  no  other  fields  on  this  subfile  to  be  valid, 

A further  check  is  made  to  determine  if  the  field 
to  be  deleted  is  a component  of  any  superfields  or 
is  the  defining  base  field  for  any  subfields.  If 
so,  the  user  is  told  of  all  superfields  and  all 
subfields  that  make  use  of  this  field.  The  user 
is  then  prompted  for  a neu  field  name  value.  If 
here  then  the  field  can  be  deleted. 

At  this  point,  the  internal  delete  entry  point  is 
defined.  If  the  field  name  to  be  deleted  does  not 
exist,  control  is  returned  to  the  calling  routine. 
Otherwise  a pointer  is  set  to  the  field  to  be 
deleted.  At  this  point  delete  forms  common 
code. 

If  the  field  appears  on  an  associate  or  subfile  or 
is  indexed,  then  the  appropriate  file  descriptor 
counts  are  updated.  If  the  associated  file  or 
index  file  is  depleted  of  fields,  the  file 
headers  are  deleted,  and  the  file  ids  made 
available  for  reassignment. 

At  this  point  the  field  is  deleted  by  the  internal 
delete  field  routine.  If  the  deleted  field  is  a 
subfile  control  field,  the  subfile  key  field  and 
the  parent  key  field  are  also  deleted, . 

The  next  field  in  the  list  to  be  deleted  is  now 
processed  in  the  afore  mentioned  manner.  After 
all  of  the  fields  have  been  processed,  the  command 
string  is  saved  in  the  current  strategy,  if  it  was 
the  delete  command  that  was  called.  Control  is 
then  returned  to  the  calling  routine. 

The  internal  procedure  DELETE  EIELD  is  used  to 
release  the  work  areas  containing  the  field 
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information,  and  to  post  the  deleted  field  list  if 
this  field  exists  on  the  disc  storage  version  of 
the  descriptor  file, 

CODING  SPECiriCAIIGHS 

1.  Source  language 

Pl/I  Kith  TSPL/I  statements. 

Suggestions  and  lechnigues 

Hot  Applicable 


2 


Figure  1.  I/O  Block  diagram 


Figure  2 . Top  level  f loxvchart 
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fOPIC  D.16  - DESCEIPTGE'  EDITOE  - DISPXAY  EIELD  COMMAMD 

A.  HODULE  MAME 

Program'-ID  - RBBEDPP 
Hoaule-ID  - DBEDDP 
Entry  Points 

DBEDEP1  - DISPIAY  Ccmmana 
UEEBDPP  Paging  Entry 

B.  AHALYST 

Barry  G*  Hazlett- 
Neot erics,  Inc» 

C.  HODDLE  EUECTION 

!This  routine  is  used  to  display  the  information 
defining  a field. 

D.  BATA  8EQUIBEHENTS 

1,  I/O  Block  Diagram 
See  Eignre  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Kot  Applicable 

b»  Punched  Card  Input  Pile 
Pot  Applicable 
c.  Input  Files 

Rot  Applicable 

3,  Output  Data  Sets 

a.  Output  Eiles 
Hot  Applicable 

b.  On-Line  Terminal  Displays 

The  various  pieces  of  information  are 
displayed  on  the  screen  one  item  per  line 
preceded  by  a descriptive  title.  Refer  to 
the  dataset  specifications  for  a description 
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cf  this  display  format.  . 
c.  rormatted  Print-Outs 
Kot  Applicable 
4,  ■Reference  tables 

The  following  external  tables  are  referenced  by 
RDBEDT5P: 

1.  'FlliD 

2.  FID 

3.  BBS 

4 . SICDRITY 

5.  SOPEE 

6.  VALID 

7.  X 

A description  of  these  tables  is  found  in  the 
dataset  specifications  of  the  DEB. 

PE0CESSIE6  EEQUIEE BEETS 

1.  Top  level  Flowchart 
See  Figure  2 

2,  Narrative 

At  the  command  entry  point  the  paging  information 
structure  is  allocated  and  initialized  and  routine 
DBEDGF  is  called  to  obtain  the  fieldname  to  be 
displayed. 

At  the  paging  entry  point,  the  paging  information 
is  set  to  point  to  the  proper  page  to  be  displayed 
and  then  join  common  code  with  the  command  entry 
point. 

At  the  start  of  the  common  code  the  number  of  the 
next  item  to  be  displayed  is  retrieved  from  the 
paging  information  and  a branch  is  taken  to  the 
appropriate  code  to  obtain  the  next  piece  of  field 
information.  If  there  is  no  information  for  this 
item  number,  the  next  item  is  pointed  to  and 
processed  as  above.  After  the  line  of  information 
is  built,  it  is  placed  in  the  screen  buffer* 

If  there  is  mere  room  in  the  buffer,  the  next  item 
is  pointed  to  and  processed  as  above.  Once  the 

screen  is  full  and  there  is  more  information  to  be 
output  in  the  forward  direction,  a paging  entry 
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point  is  setup  and  next  page  information  is  posted 
in  the  paging  information  structure*  The  buffer 
is  then  flashed  to  the  screen  after  which  control 
is  returned  to  the  calling  routine. 

CODING  SPECIFICATIONS 

1.  Source  language 

PI/I  with  TSPI/I  statements. 

Suggestions  and  Techniques 

Not  Applicable 


2 


Figure  1.  I/O  Block  Diagram 


Figure  2a. 


Top  Level  Flowchart 


Figure  2b.  Top  Level  Flowchart 
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TOPIC  D.17  - DESCBIPTCl  EDITOE  - COHBOJl  BOnilUES  HODOLE 

A.  Program -ID  - EDBEDCE 
Hoaule-ID  - DBEDCK 
Entry  Poini:s  DBE-DDA 

DBEDDS 

IBEDDX 

DBEBEF 

EBEDIA 

DBED6A 

IBED6E 

DBEDGl 

DBEDPG1 

DBEDPG2 

•B.  ANAIYST 

Barry  G.  Hazlett 
Ueoterics,  Inc. 

C.  HODULE  FOECTIOE 

This  module  consist-s  of  several  routines  commonly  used 
by  the  Descriptor  Editor.  They  are: 

1.  DEEDDA  is  used  to  delete  a field  from  an  associate 
file. 

2.  DBEDDS  is  used  to  delete  a field  from  a subfile.  . 


3,  DEEDDX  is  used  to  delete  a field  from  an  inverted 
index  file, 

4,  DBEDEE  is  used  to  expand  the  field  structure  when 
it  is  full, 

5,  DBEDFA  is  used  to  release  the  vork  areas 

containing  all  of  the  field  descriptor  and  file 
descriptor  information, 

6,  DBEDGA  is  used  to  get  and  process  the  ASSOCED 
parameter  group, 

7,  DEEDGE  is  used  to  get  and  process  a valid 

fieldname. 

B,  DBEDGB  is  used  to  get  and  process  the  conversion, 
formatting,  and  validation  routine  names  and 
validation  argument, 

9.  DBEDPG1  is  used  for  a common  paging  entry  point. 

10.  DBEDPG2  is  used  to  flush  the  buffer  to  the  screen 
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and  setup  to  allov  paging, 

BATA  EEQDIIEMEHTS 

1.  I/O  Elock  Biagram 

See  Figure  1 
•2,  Input  Bata  Sets 

a.  Parameter  Cards 
Not  Applicatle 

b.  PuucKed  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Not  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-Line  Terminal  Displays 

The  displays  output  to  the  screen  by  BBEDPG2 
are  those  setup  by  the  DISPLAY,  BEVIEW,  and 
FIELDS  commands.  Their  descriptor  can  be 
found  in  the  Dataset  Specifications  section 
of  the  DNB. 

c.  Formatted  Print-Outs 
Not  Applicable 

4,  Reference  Tables 

The  following  external  tables  are  referenced  by 

EDBEDCM; 

1 . FIELD 

2.  FLD 

3.  HDE 


4 


RFCSEC 
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5.  SECOEITY 

6.  SUPEE 

7.  VAIID 

8.  X 

a description  of  these  tables  can  be  found  in  the 
Dataset  Specifications  of  the  DWB. 

PBOCESSING  aSQOIEEHSNTS 

1.  lop  level  Elo^jchart 
See  figure  2 

2,  Narrative 

Upon  entry  into  DBEDDS  the  appropriate  subfile 
header  table  is  addressed*  The  count  of  records 
on  this  subfile  is  decremented* 

If  the  deleted  subfile  field  exists  on  disc,  then 
X, DELETE  is  posted  so  that  the  appropriate 
descriptor  will  be  deleted.  The  field  descriptor 
table  is  then  updated  after  which  control  is 
returned  to  the  calling  routine. 

Upon  entry  into  DBEDDA  the  appropriate  associate 
header  table  is  addressed.  The  count  of  records 
on  this  associated  file  is  decremented.  If  no 
fields  are  left  on  the  associate  file,  the 
associate  file  header  is  released  and  the 
associate  file-id  made  available  for 
reassignment . 

If  the  deleted  associated  field  exists  on  disc, 
then  X, DELETE  is  posted  so  that  the  appropriate 
descriptor  will  be  deleted.  The  field  descriptor 
table  is  then  updated  after  which  control  is 
returned  to  the  calling  routine. 

Upon  entry  into  DBEDDX  the  appropriate  index 
header  table  is  addressed.  The  count  of  records 
on  the  index  file  is  decremented.  If  no  fields 
are  left  on  the  index  file,  the  index  file  header 
is  released  and  the  index  file-id  made  available 
for  reassignment. 

If  the  deleted  indexed  field  exists  on  disc,  then 
X. DELETE  is  posted  so  that  the  appropriate 
descriptor  will  be  deleted.  The  field  descriptor 


PAGE  252 


table  is  then  updated  after  which  control  is 
returned  to  the  calling  routine* 

Upon  entry  into  DBEDEf,  the  number  of  permissable 
items  in  EIEID  is  raised  by  100  and  a new  larger 
FIELD  structure  is  allocated* . The  information 
from  the  old  field  structure  is  moved  to  the  new 
structure  and  then  the  old  structure  is 
released*  Control  is' then  returned  to  the  calling 
routine* 

Upon  entry  into  DBEDFA,  a control  loop  is  set  up 
to  step  through  all  of  the  existing  field 
descriptor  table*  If  the  field  descriptor  has  a 
validation  argument,  then  the  VALID  pointer  is 
setup  and  the  VALID  area  released.  If  the  field 
descriptor  has  field  security,  the  SECURITY 
pointer  is  setup  and  the  SECURITY  area  released* 
If  the  field  descriptor  defines  a super  field,  the 
SUPER  pointer  is  setup  and  the  SUPER  area 
released.  Ihe  ELD  area  is  released*  After  all 
the  field  descriptor  areas  have  been  released,  the 
FIELD  structure  is  released* 

A control  loop  is  setup  to  step  through  each 
header  descriptor  table.  If  the  file  has  record 
security,  the  RECSEC  pointer  is  setup  and  the 
RECSEC  area  released*  The  HDR  area  is  then 
released. 

After  all  file  descriptors  have  been  released  if 
the  RECLEN  field  has  field  security,  the  SECURITY 
pointer  is  setup  and  the  SECURITY  area  is 
released.  Control  is  then  returned  to  the  calling 
routine* 

Upon  entry  into  DBEDGA,  the  user  is  prompted 
whether  or  not  the  field  is  to  be  placed  on  an 
associate  file.  If  the  response  is  not  an 
acceptable  boolean  value,  he  is  given  a diagnostic 
or  prompted  fcr  an  acceptable  boolean  response. 
If  the  response  is  no  and  in  UPDATE  mode,  if  the 
field  is  already  on  an  associate  file,  the  field 
is  deleted  from  the  associate  file  by  calling 
DBEDDA*  Control  is  then  returned  to  the  calling 
routine. 

If  the  user  wants  the  field  to  be  associated,  be 
is  prompted  on  which  associated  file  the  field  is 
to  be  placed.  If  no  field  name  is  entered,  a new 
associate  file  header  is  created  and  posted*  If  a 
fieldname  was  entered,  it  must  exist  and  be 
associated*  If  the  entered  name  does  not  meet 
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this  criteria,  the  user  is  given  a diagnostic  and 
reprompted  for  which  associated  file.  If  the 
entered  field  is  associated,  then  this  associated 
file  header  record  is  addressed,  and  posted. 

The  field  descriptor  structure  is  then  updated 
after  which  control  is  returned  to  the  calling 
routine. 

Upon  entry  into  DBEDGF  the  user  is  prompted  for  a 
fieldname.  The  field  name  is  then  verified. 

If  the  name  is  invalid,  the  user  is  given  a 
diagnostic  and  reprompted  for  a correct  field 
name.  The  field  name  validation  criteria  is  set 
up  by  the  calling  routine.  It  consists  of  the 
message  id  to  prompt  with,  whether  it  is  to  be  a 
new  field  name  or  if  it  must  already  exist  and 
whether  or  not  it  can  be  a reserved  fieldname. 

If  it  is  a new  fieldname  and  the  caller  so 
reguests,  a new  FLD  structure  will  be  allocated' 
and  the  fieldname  posted  therein. 

If  the  entered  name  is  unacceptable  for  any  of  the 
prestated  reasons,  the  error  flag  is  turned  on. 
Control  is  then  returned  to  the  calling  routine. 

Upon  entry  into  DBZBGB,  a control  loop  is  setup  to 
prompt  for  each  of  the  3 routine  names; 
conversion,  formatting,  and  validation  routines 
names.  If  a name  is  entered,  it  is  verified.  For 
conversion  and  formatting  routines  if  no  name  is 
entered  and  if  the  field  type  is  not  alphanumeric, 
a default  routine  name  is  supplied.  The  routine 
names  are  posted  in  the  FID  structure. 

If  a validation  routine  was  specified,  a 
validation  argument  is  prompted  for.  To  be  valid 
it  must  contain  an  even  number  of  hexadecimal 
characters.  If  an  argument  is  entered,  the  value 
is  saved  in  a VALID  structure,  the  pointer  of 
which  is  posted  in  the  FID  structure.  Control  is 
then  returned  to  the  calling  routine. 

Upon  entry  into  DBEDPGI  the  user  is  prompted  for  a 
paging  direction  and  it  is  validated.  If  it  is  in 
error  the  user  is  given  a diagnostic  and 
reprompted  for  the  direction.  If  in  the  desired 
direction,  there  is  no  more  information  to  output, 
the  user  is'  given  a diagnostic  and  control  is 
returned  to  the  calling  routine.  The  appropriate 
routine  is  called  to  setup  the  next  page  of 
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information  to  be  displayed,  after  which  control 
is  returned  to  the  calling  routine. 

Upon  entry  into  DBEDPG2  if  there  is  more 
information  to  output  the  KOBE  DATA  flag  is  turned 
on»  If  it  is  possible  to  page  in  either 
direction,  a paging  entry  point  is  setup.  The 
information  is  flushed  from  the  buffer  to  tbe 
screen  after  which  control  is  returned  to  the 
calling  routine. 


Figure  1 - I/O  Block  Diagram 
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TOPIC  D.18  ~ PESCBIPTCB  EDITOB  - EIEEDS  COHHABD 

fl*  HOBDLE  KAHE 

Program-ID  - BPEEPEl} 

Module-ID  - DEEDED 
Entry  Points 

DEEDED 1 - FIEIDS  Commana 
DEEDED2  - Paging  Entry 

B.  . ANAXYST 

Barry  G.  Ha’zlett 
Neoterics,  Inc* 

C.  HODDIB  ED.NCTION 

In  CEEATE  ffiofle  the  EIEXDS  coffiroand  outputs  the  names  of 
the  fields  thus  far  created*  In  UPDATE  mode  the 
descriptor  descriptor  names  are  displayed, 

D.  DATA  EEQDIBEfJENTS 

-1.  I/O  Block  Diagram 
See  Figure  1 
2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Bet  Applicable 

c.  Input  Piles 
Hot  Applicable 

3*  Output  Data  Sets 

a.  Output  Files 
Bot  Applicable 

b.  "On-Xine  Terminal  Displays 

The  fieldnames  are  placed  on  the  screen,  the 
number  of  names  per  line  determined  by 
dividing  the  screen  width  by  20* 
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c,  lormattea  Print-Outs 
Eot  Applicable 
4«  Reference  Tables 

The  following  external  tables  are  referenced  by 
BDBEDFD; 

1«..  TIEID 
2.  X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  BWB» 

-E,  , PROCESSING  REQUIREMENTS 

1.  Top  level  Elowchart 

See  Eigure  2 

2*  Narrative 

If  in  CREATE  mode,  a pointer  is  set  to  the  EIEID 
structure V otherwise  in  OPIATE  mode  the  pointer 
is  set  to  an  internal  list  containing  the 
descriptor  descriptor  field  names. 

At  the  paging  entry  the  proper  page  number  is  set 
up  in  the  paging  information  structure. 

At  this  p'oint,  the  code  becomes  common  for  both 
the  command  and  paging  entry  points.  The  number 
of  the  next  field  name  to  be  displayed  is  obtained 
from  the  paging  information  structure.  Two 
control  loops  are  set  up,  one  to  build  every  line 
to  fill  the  screen  and  the  other  to  fill  each  line 
of  the  screen. 

If  there  is  more  information  to  be  displayed,  the 
paging  entry  point  is  set  up.  The  paging 
information  structure  is  posted,  the  buffer  is 
flushed  to  the  screen  and  control  is  then 
returned  to  the  calling  routine. 

E.  CODING  SPECIFICATIONS 

1,  Source  language 

Pl/I  with  TSPl/I  statements. 

2.  Suggestions  and  Technigues 
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Hot  Applicable 


DESCRIPTOR 

TABLES 


Figure  1.  I/O  Block  Diagram 
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TOPIC  D. 19  - EISCBIPTGB  EDITOl  - FIIE  COMBAND 

A,  MODULE  NAME 

Program-ID  - BDBEDEI 
Module-ID  - DBEDFI 

B,  ANALYST 

Barry  G,  Hazlet-t 
Neoterics,  Inc, . 

C,  HODULE  FUNCTION 

This  module  is  used- to  place  those  additions  and/or 
changes  from  the  descriptors  in  core  to  the  descriptor 
file. 

B,  DATA  EEQUIBEHENTS 

1,  I/O  Block  Diagram 
•See  Figure  1 
2. , Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

■b.  Punched  Card  Input  Files 
Not  Applicable 
C,  Input  Files 

Not  Applicable 
3,  Output  Data  Sets 

a.  Output  Files 

The  descriptor  file  is  a region  TSS  VISAH 
dataset  containing  all  the  information 
necessary  to  completely  define  the  data 
base. 

b.  On'’Line  Terminal  Displays 
Not  Applicable 

C,  Formatted  Print-Outs 
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Not  Applicable 

4.  Beference  Tables 

The  following  external  tables  are  referenced  by 
BDEEDJI: 

1 . EIEID 

2.  EID 

3.  FID^STEING 

4.  HDl 

5.  HDB_STBING 

6 . BECSEC 

7.  SECURITY 

8.  SOPER 

9.  VAIIB 

10.  X 

A description  of  these  tables  can  be  fonnd  in  the 
dataset  specifications  of  the  DWB. 

PROCESSING  REQUIREMENTS 

1. . Top  level  flowchart 

See  Eignre  2 

2,  Narrative 

Upon  entering  FIIE  command,  if  jnst  one  descriptor 
record  is  to  be  updated,  the  appropriate  file 
identified  is  setup,  the  file  opened  and  the 
descriptor  record  is  updated  after  which  control 
is  returned  to  the  calling  routine,  . Otherwise  all 
the  descriptor  information  is  to  be  filed  to  the 
descriptor  file.  The  user  is  prompted  for  the 
parameter  BESCOK  and  the  value  saved  for  posting 
each  header  record.  If  the  input  value  is  in 
error  the  user  is  given  a diagnostic  and  prompted 
for  a new  value. 

If  the  anchor  key  field  needs  to  be  deleted,  it  is 
deleted  from  the  anchor  and  all  associate  files. 
The  delete  file  list  is  then  processed  deleting, 
the  header,  EECLEN  key  field  and  when  applicable 
the  parent  key  field  of  all  files  listed. 

For  outputting  descriptor  information,  the  files 
are  processed  in  the  following  order:  anchor,  all 
associate  files,  then  all  subfiles. . If  the  file 
does  not  exist  on  disc  the  RECLEN  field  is 
written  out.  If  it  is  a new  region  and  the  file 
is  either  the  anchor  file  or  an  associate  file  the 
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anchor  key  fieia  loust  be  written  oot  for  a new 
subfile  the  subfile  key  field  and  parent  key  field 
are  written  cut.  If  these  or  any  other  fields 
already  exist  on  the,  file  then  only  the  changes  if 
any,  to  these  fields  are  written  out.  Record 
security  if  any  is  then  written  out. 

As  these  fields  are  output  the  field  position 
yalue  for  each  field  in  maintained  and  updated. 
2his  value  is  then  placed  in  the  ELDPOSIT  position 
for  each  field. 

The  packed  bit  fields  for  the  file  are  then 
processed,  in  the  order  in  which  they  appear  in 
the  list.  They  are  packed  four  to  a byte  and  the 
field  position  and  field  length  indicating  which 
byte  and  where  in  the  byte  respectfully  the  field 
can  be  found.  After  all  packed  bits  fields  are 
processed,  the  fixed  fields  for  the  file  are 
processed  shipping  over  the  key  field,  parent  key 
field  and  record  security  field  where  applicable. 
Then  all  varying  fields  are  processed  in  order. 

If  it  is  an  anchor  or  associate  file  all 
descriptors  if  any  are  set  up  and  processed. 
Then  the  header  record  is  setup  and  processed  and 
the  file  closed.  . The  next  file  is  processed  in 
this  manner  until  the  anchor  file,  ail  associate 
files  and  all  subfiles  are  processed. 

The  index  files  are  processed  next.  If  it  is  a 
new  file  the  EECLEN  field  is  written  out.  Each 
field  to  be  indexed  on  this  file  is  located,  setup 
and  written  cut.  The  anchor  or  key  field  on  the 
appropiate  subfile  key  field  is  setup  and  written 
out.  If  the  index  file  already  exists  then  only 
those  changes  applicable  are  written  out  to  the 
dataset.  Each  index  file  is  processed  in  this 
manner  until  all  index  files  have  been 
processed. 

After  all  the  fields  have  been  processed  the 
various  external  structures  are  marked  ind.icating 
that  the  descriptor  data  is  on  the  dataset.  The 
command  string  is  saved  in  the  current  strategy 
and  control  is  returned  to  the  calling  routine, 

?. . CODING  SPECIEICATIONS 
1,  Source  language 

PI/I  with  DBPL/I  and  TSPL/I  statements. 


Suggestions  an9  Secbni'ques 
Net  Applicable 


Figure  1 


I/O  Block  Diagram 


I ^ . V 
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TOPIC  -D.20  - PESCEIPTOP  EDITOB  - FIELD  SECURITY  COMMAND 

■A,  MODULE  SAMI 

Program-ID  - RDBEDFS 
Module-ID  - DBEDFS 

-B,  . ANALYST 

Barry  G«  Hazlett 
Neoterics,  Inc. 

C,  MODULE  FUNCTION 

This  command  is  nsed  to  define  and  setup  field  security 
for  a field  or  a group  of  fields. 

D.  DATA  REQUIREMENTS 

•1..  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

h.  Punched  Card  Input  Files 
Not  Applicable 
c.  Input  Files 

Not  Applicable 

3,  Output  Data  Sets 

a.  . ’Output  Files 

Not  Applicable 

b.  On-Line  Terminal  Displays 
Hot  Applicable 

c.  Formatted  Print-Outs 
Not  Applicable 

•4,  Reference  Tables 
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The  folloTiring  external  tables  are  referenced  by 
BDBEDPS- 

•1 . IIIID 

2.  PLI) 

3.  SECDBIIY 
. X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  D9B, 

PEOCESSIBG  BBQUIREMEUTS 

1,.  . Top  Level  Flowchart 

See  Figure  2 

2.  Narrative 

Routine  J5BEDGF  is  called  fo  obtain  an  existing 
field  name. 

If  CREATE  mode  the  user  may  enter  up  to  18  field 
names  at  one  time.  If  several  field  names  are 
entered,  fhey  are  processed  as  above. 

The  user  is  then  prompted  for  a securify  code  and 
an  add-delete  indicator.  If  no  indicator  is 

present,  add  is  assumed.  If  the  indicator  is 
invalid  or  the  security  code — is  not  an 
alphanumeric  character  string,  the  user  is  given  a 
diagnostic  and  prompted  for  a new  security  code 
value . 

f 

The  used  may  enter  up  to  18  security  codes  in  a 
parenthesesed  list. 

If  the  field  already  has  field  security  a pointer 
is  set  to  it,  'otherwise  a SECDBITY  work  area  is 
allocated. 

If  the  security  code  is  to  be  added  to  the  list, 
and  it  is  not  already  there,  it  is  added  at  the 
end  of  the  list.  Otherwise  it  is  ignored.  If  the 
security  code  is  to  be- deleted,  a search  is  made 
through  the  existing  codes  deleting  all 

occurrences  of  the  code  if  any,  . 

Once  all  of  the  entered  security  codes  have  been 
processed  a ■ check  is  made  if  any  security  codes 
are  lift  on  this  field.  If  none,  then  the 
SECURITY  work  area  is  released,  else  the  pointer 
to  SECURITY  is  posted  in  the  FLD  structure. 
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in  UPDATE  mode,  routine  DBEDFI  is  called  to 
post  the  sectirity  codes  to  the  descriptor  file. 

The  comraand  string  ’ is  saved  in  the  current 
strategy  and  control  is  then  returned  to  the 
calling  module, 

E. . CODIKG  SPECIEICATIOMS 

1,  Source  language 

Pl/I  'With  TSPl/I  statements. 

2,.  Suggestions  and  Technigues 

Hot  Applicable 


Figure  1.  I/O  Block  Diagram 
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TOPIC  D.  21  - BESCBIPTQR  EDITOR  - LOAD  DESCRIPTORS  MODULE 

A.  . MODULE  RAME 

Program-'ID  - RDBEDLD 
Hodule-ID  - DBEDLE 

B,  ANALYST 

Barry  G,  Hazleti: 

Neoterics,  Inc. 

C.  MODULE  EUNCTION 

In  create  inode  the  load  module  loads  and  sets  up  all 
field  and  header  descriptor  information.  In  update 
mode  the  load  module  loads  the  desired  descriptor 
record,  including  file  descriptors  and  dummy  descriptor 
records,  - 

D,  DATA  REQUIEEHINTS 

1.  I/O  Block  Diagram 
See  Eigure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Rot  Applicable 

b.  Punched  Card  Input  Piles 
Rot  Applicable 

c.  Input  Files 

The  descriptor  file  is  a region  TSS  EISAS 
dataset  containing  all  the  information 
necessary  to  completely  define  the  data 
'base, 

3.  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-Line  Terminal  Displays 
Not  Applicable 
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c. - Eoxmatted  Print-Oats 
Hot  Applicable 
4»  Reference  ffables 

The  following  external  tables  are  referenced  by 
PBBEDID: 

1 . Elf IB 

■2,  TLB 

3.  FID  STBIHG 

4.  HDr” 

5.  HDB_STEIHG 

6*  TICS EC 

7.  SEC OBI TT 

8.  SICOBITY^STR 

9.  SDPEE 
18.  7AL1D 
11.  X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DWB, 

PROCESSING  EEQDIREBENTS 

1.  Top  Level  Flowchart 

See  Fignre  2 


2.  Narrative 

Upon  entry  into  DBEDXD  if  all  descriptors  are, to 
be  loaded,  the  anchor  file  is  first- pointed  to, 
otherwise  the  appropriate  file  identifier  is  set 
up.  If  call  from  REVIEW  command  branch  to 
retrieve  the  appropriate  header  on  field 
descriptor  fields  as  the  file  has  been  opened  and 
the  appropriate  descriptor  read  into  core. 

In  update  mode  any  fields  which  have  been  loaded 
and  still  exist  in  worh  areas  are  released.  This 
is  a control  so  that  no  more  than  one  field 
descriptor  can  be  loaded  at. any  one  time.  Notes 
this  is  not  true  for  header  descriptor. 

The  next  descriptor  region  is  opened  starting  with 
the  anchor  region  and  the  descriptor  header  record 
read  in.  The  header  fields  are  obtained  and  all 
bit  switches  converted  to  an  alphabetic  character. 
A HDB  structure  is  allocated  and  the  header 
information  saved  therein.  If  the  file  has  record 
security,  the  security  codes  obtained,  placed  in  a 
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EEC SEC  structure  and  tooked  up  to  the  BDB 
structure. 

If  in  update  mode,  the  desired  field  descriptor 
record  is  read  in,  otherwise  the  next  sequential 
field  descriptor  is  read  in. , If  not  in  review 
mode,  it  must  be  determined  if  the  field  is  a 
dummy  descriptor.  If  it  is  then  a list  of  file 
ids  is  built  eventually  containing  all  of  the 
descriptor  regions  on  the  file  once  all  of  the 
field  descriptors  on  the  anchor  file  have  been 
processed.  This  list  is  built  from  non-blank 
entries  in  the  ASSOCFII,  IHVFILE  and  SUBEIIE 
descriptor  fields.  If  the  field  is  a dummy,  and 
in  update  mode,  the  correct  file  is  pointed  to  and 
a branch  goes  to  open  the  file  and  read  the 
desired  field  descriptor.  In  create  mode,  this 
record  is  skipped  and  the  next  descriptor  record 
in  the  region  is  read. 

If  this  field  descriptor  is  saved,  all  of  the 
field  descriptor  bit  field  values  are  translated 
to  an  alphabetic  character. 

The  field  validation  argument,  if  any,  is  obtained 
and  saved.  If  the  field  is  a superfield,  the 
component  values  are  obtained  and  saved, 
likewise,  if  the  field  has  security,  the  security 
codes  are  obtained  and  saved, 

A ELD  structure  is  allocated  and  the  field 
information  saved  therein.  The  field  name  and 
pointer  are  posted  in  the  next  available  slot  in 
the  EIELB  structure,  and  if  in  create  mode,  the 
FIB  structure  is  chained  to  the  end  of  the  proper 
file  list, 

Ehen  the  anchor  region  is  finished,  A list  of  all 
existing  descriptor  regions  is  complete.  The  next 
descriptor  region  in  that  list  is  selected  and 
loaded  as  described. 

In  review  mode  once  the  desired  descriptor  record 
from  the  desired  descriptor  region  has  been 
processed,  as  the  correct  non  dummy  field 
descriptor  has  been  loaded  in  update  mode,  control 
is  returned  to  the  calling  routine. 

In  create  mode  a search  is  made  through  all  file 
lists  to  locate  all  subfields.  For  each 
subfield,  the  defining  base  field  is  located  and 
the  base  field  name  and  offset  are  posted  in  the 
subfield  FIB  structure. 
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The  fields  within  the  file  lists  are  ordered  by 
their  field  positions  within  each  file  list  with 
all  snbfields  and  superfields  appearing  at  the  end 
of  the  ordered  lists.  Control  is  then  returned  to 
the  calling  routine, . 

CODING  SPECIFICATIONS 

1.  Source  Language 

PL/I  with  DBPL/I  statements.  ' 

Suggestions  and  Techniques 

Not  Applicable 


•2. 


Pieure  2a.  Top  Level  Flowchart 
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TOPIC  H,22  - DESCBXPTCE  EBITOl  - HOVE  COHHAHD 

A,  MODULE  SAHE- 

Program-ID  ■“  BDEIIHO 
Module-ID  - DBEDBO 

B,  , ANALTST 

Barry  G.  Hazlett 
Ueoterics,  Ire, 

C*  MODULE  rUMCIIOH 

The  MOVE  command  permits  the  user  to  reorder  fields 
within  any  field  list. 

D,  DATA  REQUIBEMENTS 

1,..  I/O  BLOCK  DIAGRAM 

See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Bot  Applicable 

b.  Punched  Card  Input  Files 
Eot  Applicable 

c.  Input  Files 
Mot  Applicable 

3.  Output  Data  sets 

a.  Output  Files 
Mot  Applicable 

b.  On-Line  Terminal  Displays 
Not  Applicable 

c.  Formatted  Print-Outs 
Mot  Applicable 


4 


Beference  Tables 
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The  folio-wing  external  tables  are  referenced  by 
EDBEDMO: 

1.  PID 

2.  BBS 

3.  X 

A description  of  these  tables  can  be  fo«Ti3  in  the 
dataset  specifications  of  the  DI?B« 

E.  PEOCESSIHG  BEQUIEEHENTS 

1.  Top  level  Plowchart 
See  figure  2 

2.  Narrative 

The  user  is  prompted  for  the  new  position  field 
name.  If  the  entered  field  name  does  not  exist, 
the  user  is  given  a diagnostic  and  prompted  for  a 
ne^H  fieldname.  The  new  position  fieid  name  cannot 
be,  the  anchor  key  field  if  the  anchor  file  has 
record  security,  the  subfile  parent  key  field  if 
the  subfile  has  record  security  or  the  subfile  key 
field,  or  the  EECIEN  field.  If  any  of  these 
conditions  are  met,  the  user  is  given  a diagnostic 
and  reprompted  for  a new  position  fieldname,  A 
superfield  has  no  field  position.  If  a subfield 
is  specified,  the  defining  base  field  is  located 
and  used  as  the  new  position  fieldname.  All  other 
fields  are  unacceptable. 

The  user  is  prompted  for  the  field  to  be  moved. 
To  be  valid,  the  field  must  exist  and  must  not  be 
a reserved  fieldname,  must  appear  in  the  same 
field  list  as  the  new  position  field  name  and 
must  not  be  a superfield  or  a subfield.  If  the 
field  is  invalid,  the  user  is  given  a diagnostic 
and  reprompted  for  the  field  to  be  moved. 

The  field  to  be  moved  is  decoupled  from  the  list 
by  resetting  the  appropriate  forward  and  backward 
pointers.  It  is  then  threaded  into  its  new 
position  by  setting  the  appropriate  forward  and 
backward  pointers. 

The  command  string  is  saved  in  the  current 
strategy  and  then  control  is  returned  to  the 
calling  routine, 

E,  CODING  SFECITICATIGHS 
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1*.  Source  language 

PL/I  Twith  H'SPIVI  statements. 
2.  Suggestions  and  Technigues 
Not  Applicable 


\ 


-iTZ-.'X- 
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TOPIC  D.23  - DESCBIPTCB  EDITOB  - PATCH  COHHAND 

A.  MODHXB  MHE 

Program~ID  - EPBIBPA 
Hodtlle-ID  - DBEDPA 

B«  AHALXST 

Barry  G*  Ha'zle-tl: 

Neoterlcs,  Inc* 

C.  MODOIE  rUNCTION 

The  Patch  commanH  permits  the  user  to  patch  the  value 
in  any  descriptor  record  in  any  description  region  in 
the  descriptor  tile.  The  record  to  he  patched. roust  he 
identified  by  use  of  the  EE VIEW  command. 

D.  DATA  SEQHIEEMENTS 

1*  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Kot  applicable 

b.  Punched  Card  Input  Piles 
Sot  applicable 

c.  Input  Files 
Hot  Applicable 

3,  Output  Data  Sets 

a.  Cutput  Files 
Not  Applicable 

b.  On-line  Terminal  Displays 
Net  Applicable 

c.  Formatted  Print-Outs 
Not  Applicable 
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4»  Seference  Tables 


The  follcwing  external  tables  are  referenced  by 
BBBEDPA: 


1 

2 

3 

4 

5 
€ 
7 


ELD 

HDS 

BECSEC 

SECDBIT7 

SUPEB 

VALID 

X 


1 description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DWB. 

PBOCESSIBG  BEQDIBEMEBTS 

1.  Top  level  Flowchart 
See  Figure  2 

2.  Narrative 

The  BEVIET?  command  indicates  in  X that  a BEVIEW 
has  been  done  and  it  is  alright  to  patch,  BEVIEW 
also  indicates  whether  the  field  to  be  patched  is 
a field  or  header  descriptor. . If  a BEVIEB  has  not 
been  done  the  user  is  given  a diagnostic  and 
control  is  returned  to  the  calling  routine. 

The  user  is  prompted  for  his  patch  in  the  form 
‘'3ceywGrd=test«,  The  keyword  is  checked  to  see  if 
valid.  If  not,  the  patch  is  ignored,  the  user 
given  a diagnostic  and  reprompted  for  the  patch. 
If  the  name  is  valid,  a branch  is  taken  to  the 
piece  of  coded  which  actually  posts  the 
appropriate  field. 

In  each  of  the  sections  of  code,  one  for  each 

descriptor  field-  name,  a resonableness  check  is 

made  on  the  patch  text,  to  assure  that  the  data 
will  he  accepted  by  the  validation  routines  when 
posting  the  information  to  the  descriptor  file. 

Defer  to  the  Descriptor  Editor  Users  Guide  for  the 
acceptable  range  and  form  of  the  patch  texts. 

The  user  may  enter  a parenthesesed  list  of 
patches. 

After  all  the  patches  have  been  posted  in  the 

descriptor  table  work  areas,  they  must  then  be 
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posted  to  the  descriptor  data  set,‘  The  rontiae 
BEEBTtS  is  called  to  post  the  appropriate  field 
descriptor,  or  the  routine  DBEDFI  is  called  to 
post  the  appropriate  header  descriptor.  The 
routine  called  depends  on  whether  the  user  is 
patching  a field  descriptor  or  a header 
descriptor.  Control  is  then  returned  to  the 
calling  routine. 

E.  CODING  SPECIFICATIONS 

1,  Source  language 

Pl/I  with  TSEI/I  statements, 

2,  Suggestions  and  Techniques 
Net  Applicable 


Figure  !•  I/O  Block  diagram 
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TOPIC  D.24  ^ DESCEIPTOE  EDITOB  - PEINT  COHHAHD 

A,  HODOIE  NAME 

Program-ID  - EDBEDPl 
Module-IE  -DEEDPE 

B,  ANALYST 

Barry  G.  Hazlett 
Neo'terics,  Inc. 

C,  MODULE  EUNCIION 

The  PEINT  command  gives  the  user  a formatted  printout 
of  the  descriptor  information  as  it  exists  in  core  at 
the  time  the  print  is  issued. 

-D.  , DATA  EEQUIEEHENTS 

1.  I/O  Block  Diagram 
See  Eigure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Net  Applicable 

c.  Input  Piles 
Not  Applicable 

3.  Output  Data  Sets 

a.  Output  Piles 

The  output  data  from  EDBEDPE  is  placed  in  the 
TSAH  data  set  LIST.DESC(O)  from  where  it  is 
printed  on  the  high  speed  printer  by  TSS, 
Eor  the  details  of  the  data  set  refer  to  the 
dataset  specifications, 

b,  'On-Line  Terminal  Displays 
Not  Applicable 


PAGE  302 


c.  Iormatt€cl  Prin-t-Outs 

The  information  stored  in  LIST.DESC(O)  is 
printed  -using  column  one  of  each  record  as  a 
carriage  control. 

N Reference  Tables 

The  following  external  tables  are  referenced  bv 
RDBIDPBs 

1 . TIEID 

2 . ILD 

3.  HDR 

4.  SECSEC 

5.  SECURITY 

6.  SUPER 

7.  VALID 

8.  X 

A description  of  these  tables  can  be  found 
dataset  specifications  in  the  of  the  DWB. . 

E, , PROCESSING  REQUIREKENTS 

1,  Top  Level  Elowchart 
See  Pigure  2 

2.  Narrative  

The  generation  data  group  LIST.DESC  is  created 
using  the  routine  ASaCAT.  The  next  generation  is 
created  using  the  routine  ASMDD.  A DCE  is  created 
for  the  output  file  by  the  routine  ASHDCB,  the 
JPCB  set  up  by  the  routine  ASMPNDS,  and  the 
dataset  opened  by  the  routine  ASHOPEN. 

The  title  lines  for  the  data  base  name  are  output 
by  the  routine  ASHPUT,  The  data  base  name  is 
output  followed  by  two  trailing  title  lines. 

The  title  lines  for  the  field  descriptors  are 
output.  The  lines  of  field  information  for  each 
field  are  built  and  output. 

After  the  field  information  is  processed',  the 
title  lines  for  the  header  descriptor  information 
are  written  out.  The  lines  of  header  information 
for  each  descriptor  region  are  built  and  written 
out. 

The  LIST.DESC  dataset  is  closed  by  calling  the 
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routine  ASHCIOS  and  a printer  listing  of  the 
information  is  generated  by  using  the  routine 
ASMPR  after  «hich  control  is  returned  to  the 
calling  routine. 

CODING  SPECIFICATIONS 

1.  . Source  Language 

PL/I  with  TSPL/I  statements. 

Suggestions  and  Technigues 

Not  Applicable 


2 


descriptor 

TABLES 


Figure  1. 


I/O  Block  diagraiE 


Figure  2.  Top  level  flox^chrart 


PAGE  306 


TOPIC  D.  25  - DESCBIPTOE  EDITOE  - EECOED  SECUSITY  C0M8AKD 

•a,.  80DULE  NAHE 

Program-ID  - EDBEDES 
Hodule-ID  --  PBEEDES 

B.  AKSIYST 

Barry  G.  Hazlett 
Heoterics,  Inc. 

C.  aODTJLE  FUNCTION 

This  command  is  used  to  create  and  define  record, 
security  for  any  data  base  file  except  for  indicies. . 

B,  DATA  REQUIEEMENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Hot  Applicable 

c.  Input  Files 
Not  Applicable 

3.  Output  Data  Sets 

a.  'Output  Files 
Not  Applicable 

b.  On-Line  Terminal  Displays 
Not  Applicable 

c.  Formatted  Print-Outs 
Not  Applicable 

4.  Reference  Tables 
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The  follOT?ing  external  tables  are  referenced  by 
BBBEDBS? 

1.  HELD 

2.  TXD 

3.  P1D_STEIMG 

4.  HBB 

5.  EEC SEC 
€.  X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DKB. 

PEOCBSSING  SEQUIBEBENTS 

1*  Top  Level  Elo«chart 

See  Eigure  2 

2*  Narrative 

Eoutine  DBEDGF  is  called  to  obtain  a fieldname 
used  to  define  on  which  file  record  security  is  to 
be  placed.  If  in  update  mode  and  the  header 
record  is  not  loaded,  DBEDII)  is  called  to  load  the 
header.  If  there  is  no  record  security  currently 
defined  for  the  file  in  OPDATE  mode,  the  user  is 
given  a diagnostic  and  control  is  returned  to  the 
calling  routine. 

The  user  is  prompted  for  a record  security  code. 
The  add-delete  indicator  is  removed  from  the  code 
and  validated.  If  it  is  invalid,  the  security 
code  is  rejected,  the  user  is  given  a diagnostic 
and  xepronipted  for  the  security  coded.  If  no 
indicator  is  entered,  "ADD”  is  assumed. 

The  security  code  is  removed  from  the  parameter. 
If  this  is  not  an  alphanumeric  character  string, 
the  security  parameter  is  rejected,  the  user  is 
given  a diagnostic  and  reprompted  for  the 

security  code. 

The  security  mask  to  be  valid  must  be  a two  digit 
hexadecimal  character  string.  If  it  is  invalid, 
the  security  parameter  is  rejected,  the  user  is 
given  a diagnostic  and  reprompted  for  the 

security  parameter. 

Once  the  security  parameter  is  validated,  it  is 
saved  in  an  internal  work  area.  The  user  may 
enter  a list  of  security  parameters  as  a list  in 
parentheses.  Each  security  parameter  is  obtained 
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from  the  user  and  processed  as  above. 

If  record  security  has  been  previously  defined  for 
the  file,  a pointer  is  set  up  to  the  file  header 
and  record  security  information.  Otherwise  a 
record  security  field  is  created  and  placed  in 
the'  appropriate  position  in  the  fixed  field  list 
of  the  file,  A record  security  save  area  is 
allocated  and  initialized, 

& control  loop  is  set  up  to  process  each  entered 
security  code.  The  existing  security  list  if  any 
is  searched  for  the  entered  security  code.  If  the 
security  code  exists  and  the  new  code  is  to  be 
added,  the  two  security  masks  are  logically  OR*ed 
together  and  the  result  posted  in  record  security 
structure.  If  the  code  is  to  be  deleted,  the  two 
security  mask  are  logically  exclusively  OR'ed  and 
the  result  placed  in  the  record  security 
structure.  If  the  security  code  is  not  in  the 
existing  list  and  it  is  to  be  added,  it  is  placed 
at  the  end  of  the  existing  list.  If  the  code  to 
be  deleted  and  it  does  not  appear  in  the  list,  it 
is  ignored.  Each  security  code  is  processed  in 
this  manner. 

After  all  security  code  have  been  processed  and 
the  record  security  list  is  empty,  the  area  is 
released  and  the  record  security  field  deleted 
from  the  file. 

If  in  UPDATE  routine  DBEDEI  is  called  to  post  the 
record  security  to  the  descriptor  file.  The 
command  string  is  saved  in  the  current  strategy 
and  then  control  is  returned  to  the  calling 
module , 

CODING  SPECIEICATICNS 

1,  Source  language 

Pl/I  with  TSPl/I  statements. 

Suggestions  and  Techning.ues 
Not  Applicable 


2, 


Figure  1.  I/O  Block  diagram 


Figure  2 . Top  level  flowchart 


PAGE  311 


TOPICS  D.26  - BISCEIPTOE  EDITOB  - EESTOEE  COHMAND 

A«  HODULE  SAHI 

Program-ID  --  SDBEDET 
!3oaule**IE  - DBEDET 

1,  AEAIYST 

Barry  G»  Ha^lett 
Neo-terics,  1tic« 

C.  HODOXE  EUKCTION 

This  contmand  is  used  to  restore-  the  descriptor  tables 
from  a VSAH  data  set  to  njemory,  so  that  the  user  may 
continue  to  create  and/or  modify  the  descriptors  from 
their  point  of  existence  at  the  time  the  checkpoint  -was 
issued, 

33.  DATA  EEQDIEEHEHTS 

1.,  I/O  Block  Eiagram 
See  Eigure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Kot  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  input  file  is  a TSS  VSAM  data  set  named 
DESCBP.CHKPOINT.  Eefer  to  the  dataset 

specifications  for  a description  of  this  data 
set. 

3.  Output  Data  Sets 

a.  'Output  Piles 
Net  Applicable 

b.  On  Line  Terminal  Displays 
Not  Applicable 
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c,  formatted  Print-Outs 
Hot  Applicable 
4*  Reference  Tables 

The  fclloTJxng  . external  tables  are  referenced  by 
RBBEDRT; 

1.  IIEID 

2.  TIB 

3.  FLB_STBIHG 

4.  HBE 

5.  HBE^STBIHG 

6.  BECSEC_STB 

7.  SECOBIT-Y^STE 
8*  SUP1B_STE 

s . valib” 

10.  X 

The  description  of  these  tables  is  in  the 
specifications  of  the  dataset  BWB, 

E, . PROCESSING  REQUIREMENTS 

1,  Top  Level  Flowchart 
See  Figure  2 

2.  Narrative 

Upon  entry  into  EBBEBET  a BCB  is  set  up  for  the 
dataset  DESCRP. CHKPOINT  by  calling  the  routine 
ASHDCE,  ASEBB  is  then  called  to  create  a JFCB  for 
the  data  set  and  ASMFNBS  is  called  to  setup  the 
JFCB.  Any  and  all  existing  field  descriptors  and 
file  descriptors  are  released  and  then  the  EIEIB 
structure  itself  is  released. 

ASaoPEN  is  called  to  open  the  dataset.  That  part 
of  the  X structure  which  was  saved  is  read  in  over 
top  of  the  same  part  of  the  existing  X strucare. 

The  FIELD  structure  is  allocated  next.  Note  that 
the  variable  defining  the  sixe  of  FIEIB  structure 
is  in  that  part  of  X which  has  just  been  restored. 
The  FIELB  structure  is  read  in  overlaying  the  just 
allocated  existing  FIELB  structure. 

A field  descriptor  is  read  into  a work  area,  . A 
FLB  structure  is  allocated  on  the  field 
information  moved  into  it.  If  the  FLB  has  field 
security,  a validation  argument,  or  is  a super 
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field,  the  appropriate  structures  are  allocated, 
the  information,  moved  into  them,  and  the  pointers 
in  FI-D  setup  accordingly.  The  changed  flags  in 
FID  are  setup  so  that  all  of  the  field  descriptor 
information  ■will  be  forced  out  to  disc  when  the 
FILE  command  is  issued.  Each  field  descriptor  is 
processed  in  this  manner, 

a file  descriptor  is  read  into  a work  area,  hn 
BDE  structure  is  allocated  and  the  header 
information  moved  into  it.  If  the  file  has  record 
security,  a RECSEC  structure  is  allocated,  the 
information  moved  into  it,  and  the  pointer  posted 
into  the  HDR  structure.  The  HDE  pointer  is  posted 
into  the  proper  slot  in  X,HE1D_TAB,  Each  header 
descriptor  is  processed  in  this  manner. 

The  dataset  DESCRP.CHKPOINT  is  then  closed  and 
control  is  returned  to  the  calling  program, 

CODING  SPECIFICATIONS 
1,  Source  Language 

PL/I  Kith  TSPL/I  statements. 

Suggestions  and  Techniques 
Not  Applicable 


2, 
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TOPIC  D.27  - DESCEIPTOB  EDITOR  - EEVIEP  COMMAND 


a.  MODULE  Na«i 

Program-ID  - EDBEBE7 
Module-ID  - DBEDR7 
Entry  Points: 

DBEDS71  - BeTriew  Command 
DBEDBV2  - Paging  Entry 

B.  ANALYST 

Barry  G,  Hazlett 
Neoterics,  Inc, 

C.  MODULE  EUNCTION 

This  command  is  used  to  present  the  descriptor 
information  to  the  user  of  any  descriptor  record  in  any 
descriptor  region  in  the  descriptor  file.  Review 
points  to  the  record  to  be  patched  by  means  of  the 
PATCH  command, 

D.  DATA  EEQOIBEHENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  File 
Not  Applicable 

c.  Input  files 

The  data  base  descriptor  file  is  a TSS  VISAH, 
file  maintained  by  DBPAC,  containing  the 
information  defining  and  detailing  the 
information  contained  in  the  data  base. 

3,  Output  Data  Sets 
a.  Output  Files 

Not  Applicable 
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b.  On-line  lerminal  Displays 

The  various  pieces  of  information  contained 
in  the  descriptor  record  are  displayed  on  the 
screen  precesded  by  the  descriptor  descriptor 
field  name.  All  fixed  fields  are  displayed 
sithin  a 20  character  string.  The  number  of 
items  per  line  for  fixed  field  items  is 
determined  by  dividing  the  screen  width  by 
20,  IJhe  varying  elements  are  display  one  per 
line,  with  continuation  lines  if  necessary, . 

c,  formatted  Print-Outs 
Hot  Applicable 

4,  References 

The  following  external  tables  are  referenced  by 
SBBEDRV; 

1.  TIE 

2.  HDR 

3.  EEC SEC 
«.  SSCnRITY 

5,  SOPER 

6,  VALID 

7,  X 

A description  of  these  tables  is — ^found  in  the 
dataset  specifications  of  the  dataset  DHB. 

PROCESSING  REQUIREMENTS 

1,  . Top  level  Ilowchart 

See  figure  2 

2,  Narrative 

At  the  command  entry  point  the  paging  information 
structure  is  allocated  and  initialized.  The  user 
is  prompted  for  the  descriptor  file  a region  id 
that  he  wishes  to  review  from.  If  the  region  id 
is  invalid,  the  user  is  given  a diagnostic  and 
prompted  for  a new  region  id. 

The  user  is  prompted  for  the  name  of  the 

descriptor  record  he  wishes  to  review  from  the 
descriptor  region.  If  the  descriptor  name  is 
invalid,  the  user  is  given  a diagnostic  and 
prompted  for  a new  descriptor  name.  If  the 
descriptor  exists  the  routine  DBEDID  is  called  to 
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load  the  descriptor  data*  If  a loading  error 
occured,  the  user  is  given  a diagnostic  and 
prompted  for  a new  descriptor  value. 

The  paging  information  structure  is  setup  to  point 
to  the  first  page  of  information  to  be  displayed. 
At  which  point  the  command  entry  and  paging  entry 
join  in  common  code. 

At  the  paging  entry  point,  the  paging  information 
is  set  to  point  to  the  proper  page  to  be  displayed 
and  then  join  common  code  with  the  command  entry 
point. 

At  the  start  of  the  common  code,  the  number  of  the 
next  item  to  he  displayed  is  retrieved  from  the 
paging  information  and  a branch  is  taken  to  the 
approprate  code  to  obtain  the  next  piece  of 
descriptor  information.  Seperate  pieces  of  code 
exist  for  each  field  descriptor  and  file 
descriptor  descriptor  fields.  After  the  piece  of 
information  is  built,  it  is  inserted  in  the  output 
line.  If  there  is  sufficient  room  in  the  output 
line  for  more  data,  the  next  item  of  information 
is  obtained  as  above.  If  the  line  is  fall,  it  is 
put  info  the  fS  screen  buffer. 

If  there  are  more  lines  of  screen  available,  they 
axe  built  and  processed  as  above.  This  continues 
until  either  the  screen  buffer  is  full  or  all  of 
the  information  has  been  exhausted.  If  the 
screen  is  full  and  there  is  more  information  to 
output  in  the  forward  direction,  a paging  entry 
point  is  setup  and  the  next  page  of  information  is 
posted  in  the  paging  information.  The  buffer  is 
then  flashed  to  the  screen. 

The  X structure  is  posted  as  the  descripter  region 
and  field  name  of  the  record  EEVIEW’ed  so  that  the 
user  may  use  the  PATCH  command  if  he  desires, 
after  which  control  is  then  returned  to 
calling  routine, 

CODING  SPECIFICATIONS 

1,  Source  Language 

PL/I  with  TSPI/I  and  DBPL/I  statements. 

Suggestions  and  Techniques 
Not  Applicable 


2 


DESCRIP- 
TOR FILE 


Figure  1.  I/O  Block  diagram 
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Figure  2a.  Top  level  flowchart 
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TOPIC  D..28  ~ DESCEIPTOE  EDITOR  - SAVE  STRATEGY  COBHAND 

aODULE  SAHE 

Program-ID  - RDBEBSS 
Module- ID  - DBEDSS 

B.  fiNAIYST 

Barry  G.-  Hazlett 
Neoterics,  Inc, 

C.  MODULE  EUNCTION 

The  command  is  used  to  create  and  save  in  the  strategy 
data  set,  a list  of  Descriptor  Editor  commands'  which 
when  execut^ed  at  any  future  time  will  create  a set  of 
descriptors  exactly  like  those  that  exist  in  core  at 
the  time  the  SAVSTEl  command  is  issued, 

D.  DATA  REODISEHENTS 

1.  .1/0  Block  Diagram 

See  Eigure  1 
2.,  Input  Data  Sets 

a.  Parameter  Cards 
Rot  Applicahle 

b.  Punched  Card  Input  Files 
Not  applicable 

c. .  Input  Files 

Not  applicable 
3»  Output  Data  Sets 

a.  Output  Files 
Not  applicable 

b.  On-Line  Terminal  Displays 

Rot  Applicable  . 


c 


Formatted  Print-Outs 


Preceding  page  blank 
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Not  Applicable 
4.  Reference  Tables 

The  following  external  tables  are  referenced  by 
RDBEPSS; 

1.  TLD 

2.  HDl 

3.  SEC SEC 

4.  SECDRITI 

5.  SnPES 

6.  VAIID 

7.  X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DWB. 

ESOCESSIUG  EEQUIBIHINTS 

1.,  Top  Level  flowchart 

See  figure  2 

2.  Narrative 

Opon  entry  into  SAVSTST,  the  user  is  prompted  for 
the  strategy  name  in  which  the  Descriptor  Editor 
commands  are  to  be  saved.  If  the  name  is  not  of 
the  proper  form  or  a strategy  by  that  name 
already  exists,  the  user  is  given  a diagnostic  and 
prompted  for  a new  strategy  name. 

Once  a valid  strategy  name  is  obtained,  the 
HAINTAIN  and  EDIT  command  strings  are  saved  in 
the  strategy.  This  initializes  the  strategy.  The 
internal  subroutine  SA7E_ELD  is  called  to  save 
the  ADD  command  to  create  the  anchor  file  Key 
field, 

A control  loop  is  set  up  to  process  each  of  the  20 
possible  files  in  the  order  of  anchor  file^ 
associate  file  and  then  subfiles,  With  each 
existing  file  each  field  list  is  processed  in  the 
order  of  packed  bit  fields,  fixed  fields,  and  then 
varying  fields.  Each  field  list  is  processed  from 
the  start  of  the  list  to  the  end  of  the  list. 

The  SSYE_EID  command  is  called  for  each  field  to 
create  and  save  the  appropriate  command  string. 

The  fields  COMMENTS,  FEEEEORM,  the  subfile  key 
field,  and  the  subfile  parent  Key  fields  are 
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skipped  as  they  are  created  thra  the  adding  of  the 
anchor  key  field  or  the  CREATSOB  command.  d!he 
record  security  field  is  skipped  if  encountered 
and  processed  after  all  other. fields  on  the  file 
have  been  processed.  All  the  fields  on  all  of  the 
files  are  processed  in  the  manner  and  order. 

If  the  EECLES  field  has  field  security,  the 
SAyE_ES  is  called  to  build  and  save  the  FLDSEC 
command. 

After  all  of  the  fields  and  files  have  been 
processed,  the  EIIE  and  END  commands  are  saved  in 
the  strategy,  after  "which  time  control  is  returned 
to  the  calling  routine. 

In  the  SAVE^IID  internal  procedure,  if  the  field 
is  a subfile  control  field  the  CREATSEB  command 
string  is  built  else  of  the  field  is  a superfield 
the  SOPERFXD  command  string  is  built,  ctheruise 
the  ADP  command  string  is  built.  The  appropriate 
command  string  is  saved  thru  use  of  the  routine 
TSPDT6. 

The  internal  entry  SAVE^FS  is  • defined  at  this 
point  to  save  the  field  security  if  any.  This 
code  is  also  part  of  the  SAVE_ELD  procedure.  If 
the  field  has  field  security  defined  on  it,  a 
EIDSEC  command  string  is  built  or  saved  in  the 
strategy  through  use  of  the  routine  TSPBTG, 
Control  is  then  returned  to  the  calling  point  in 
SAySTBT. 

CODING  SPECIFICATICNS 

1,  Source  language 

Pl/I  nith  TSPI/I  statements. 

Suggestions  and  Techniques 
Not  Applicable 


2 


KDBEDSS 


STRATEGY 
DATA  SET 


Figure  1.  I/O  Block  diagram 
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Figure  2b.  Top  level  flowchart 
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TOPIC  -D,  29  - DESCBIPTCR  EDITOR  - SDPEHPIEID  COHHAND 

A.  ■ HODOIE  NAHE 

Prograin-ID  - EDBEDSD 
Eodule-ID  - DBEDSO 

•B.  ANALYST 

Barry  G*  Hazlet-t 
Neoterics,  Inc, 

C.  NODDLE  PDNCTION 

The  SDPEBPLD  commands  allow  the  user  to  define  a 
superfield  descriptor, 

D,  . DATA  REQDIEBHENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

h.  Punched  Card  Input  Files 
Not  Applicable 
c.  Input  Files 

Net  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 
Net  Applicable 

b.  On-Line  Terminal  Displays 
Not  Applicable 

c.  Formatted  Print-Outs 
Not  Applicable 

4,  Reference  Tables 
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The  following  external  tables  are  referenced  by 
BDBEDSD: 

1.  FIELB 

2.  PID 

3.  P1D_STEING 

4.  -BBS 

5.  SUPEE 

6.  VALID 

7.  X 

A description  of  these  tables  can  be  found  in  the 
dataset  specifications  of  the  DWB. 

PBOCESSIHG  EEQDIEEHIWTS 

1.  Top  Level  flowchart 
See  Figure  2 

2,  Narrative 

Upon  entry  into  SUPEBFLD,  routine  DBEDGF  is  called 
to  obtain  a new  fieldname. 

A FLD  structure  is  allocated  and  initialized. 
Eoutine  DBEDGB  is  called  to  obtain  any  conversion, 
formatting  and  validation  routines  and  validation 
argument. 

The  user  is  prompted  for  a list  of  field  names 
which  are  to  be  the  superfield  components.  Each 
component  is  processed  in  the  following  manner. 
If  no  internal  external  indicator  is  present, 
external  fcrm  is  assumed.  If  an  indicator  is 
present,  it  is  separated  from  the  field  name.  If 
the  indicator  is  invalid,  the  user  is  given  a 
diagnostic  and  prompted  for  a new  component  value. 
To  be  valid  the  component  fieldname  must  be  the 
name  of  an  existing  field.  In  addition,  for  a 
field  having  more  than  one  component,  the 
component  list  is  limited  to  at  most  one 
multielement  field  and  all  if  any  subfile 
components  roust  be  from  the  same  subfile.  If  the 
component  fieldname  is  invalid,  the  user  is  given 
a diagnostic  and  prompted  for  a new  component 
value. 

After  all  the  components  are  entered,  and 
processed,  they  are  saved  in  a SUPEE  structure  and 
the  pointer  stored  in  the  FLD  structure. 

Next  it  is  determined  on  which  descriptor  file  the 
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superfield  is  to  ie  placed.  If  all  the  components 
are  from  one  file,  then  the  superfield  descriptor 
is  placed  in  the  descriptor  region,  Tf  the 
components  are  all  from  one  associate  file  and  one 
subfile  and  the  subfile  is  defined  off  of  that 
associate  file,  the  superfied  descriptor  is  placed 
in  that  associate  descriptor  region.  All  other 
superfield  descriptors  are  placed  in  the  anchor 
descriptor  file. 

The  SUPEEFLD  command  string  is  saved  in  the 
current  strategy  and  control  is  then- returned  to 
the  calling  routine, 

F, , CODING  SPECIFICATIONS 

1. -  Source  language 

Pl/I  with  TSFl/I  statements, 

2,  Suggestions  and  Technigues 
Net  Applicable 
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Figure  1.  I/O  Block  diagram 
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TOPIC  D.30  - IMBEX  PILE  MEEGE 


A.  MODOIE  NAHE 

Saintenance  - Pile  Berger 
Program^ia  - BDBIEEH 
Hodul-e-Id  BBIEDM 

B.  ANAtyST 

Edward  Bclntire 
Neot erics,  Inc. 

C.  HOBBLE  PUJJCTIOH 

The  merge  module  is  an  independent  program  whose 
function  is  to  create  an  updated  index  file  for  a data 
base.  The  updating  of  the  index  file  can  be  done  in 
place  or  to  a new  index  file.  This  new  index  file  will 
be  named**  *INBHBG.*  //FILE  NAME//:  * //El  ELD  NAME** 
This  module  will  also  allow  for  ■ the  processing  of 
duplicate  records  if  deemed  necessary. 

D.  DATA  EEQDIBEHEHTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a^  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 

The  merging  utility  is  most  often  invoked 
from  a terminal  in  conversational  mode. 
However,  it  is  possible  to  initiate  the  task 
in  the  non-conversational  mode.  In  batch 
mode',  the  format  of  the  punched  card  input  is 
the  same  as  when  terminal  input  is  used  to 
invoke  the  routine. 

c.  Input  Files 

1.  Index  File:  The  primary  input  to  the 

combine  program  is  the  current  index 
file  that  is  to  be  updated,  and  the 
update  index  file  that  is  to  be  combined 
.with  the  current  index.  The  anchor 
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descriptor  file  is  needed  to  provide 
field  information. 

2,  Parameter  Pile:  If  the  user  wishes  to 

stop  processing  he  may  do  so  by  pressing 
attention  and  responding  *y*  to  the 
prompt  message,  Ihus  a parameter  file 
is  created  for  input  to  further 
restarts,  Ihis  file  consists  of  the 
last  key  processed  on  the  current  index 
file.  This  file  is  a VSAM  file  used 
only  in  the  combine  program, 

d,  On-Line  Terminal  Entries 

All  of  the  terminal  entries  to  the  merge 
program  are  in  the  form  of  responses  to 
prompting  messages  from  the  program  itself. 
The  one  exception  to  this  rule  is  the  initial 
command  with  its  parameter  to  invoke  the 
procedure, 

3,  Output  Data  Sets 

a,  . Output  Piles 

The  output  data  set  is  the  index  file  created 
by  the  combine  program.  This  data  set  can 
take  two  forms: 

1,  The  current  index  file  updated 
inplace, 

2.  A new  file  created  by  the  merging  of  the 
current  index  with  the  update  index,  . 

b.  On-Line  Terminal  Displays 

All  on-line  terminal  displays  for  the  combine 
program  follow  the  same  format.  The  TSPL/1 
facility  of  the  system  is  utilized  to  request 
entries  at  the  terminal  and  display  progress 
information. 

c,  formatted  Print-Outs 
Sot  Applicable 

d.  Punched  Card  Output  Piles 
Kot  Applicable 


4 


Beference  TIables 
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Not.  Applicable 
PROCESSING  EEQUIEEHENIS 
1,  , Top  level  Plowchart 

See  Figure  2 
2t  Narrative 

a.  Prompting 

Prompt  the  user  for  first  pass.  If  it  is  not 
the  first  pass,  go  and  read  the  parameter 
file.  Prompt  the  user  for  the  anchor  file 
name’,  for  ne-H  file  creation  or  merge  in 
place,  for  the  processing  of  duplicates  or 
not,  and  for  the  inverted  field  name.  The 
user  must  enter  a valid  response  to  all  of 
the  prompts  or  he  will  be  reprompted,  A read 
sequentially  of  the  anchor  descriptors  is 
done-  until  a fixed  field  with  an  offset  of 
four  (4)  is  found.  That,  in  fact,  is  the  key 
descriptor  and  its  length  is  saved.  The 
index  field  is  also  checked  for  validity,  if 
it  is  not  a valid  index,  then  a reprompt  is 
initiated.  Following  this  the  index 
descriptors  are  opened  and  read  sequentially 
until  the  index  field  length  is  obtained,  and 
the  spanned  indicator  is  checked  and  it*s 
value  is  saved.  In  all  of  the  above  cases  if 
a critical  error  is  encountered  an  error 
message  is  displayed  and  the  program  is 
terminated, 

b.  TSrite  Parameter  File 

If  the  user  deems  it  necessary  to  stop 
processing  during  the  combine  operation,  he 
can  press  the  attention  button  and  the  total 
records  processed  will  be  displayed.  Also,  a 
message  will  be  displayed  asking  if  he  wishes 
to  quit  processing,  When  the  user  replys 
with  a quit  processing  command  the  following 
occurs: 

1.  Quit  switch  is  set, 

2,  Processing  is  continued  until  a clean 
close  can  be  carried  out,  . 

Parameter  file  is  opened  and  ' the  key  of 
the  last  record  written  is  written  to 
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the  parameter  file. 

Parameter  file  is  ciosed, 

5.  Program  branches  to  end  of  job 
ron tines. 

Bead  anchor  Descriptors 

DBPac  is  . utilized  to  read  seguentially  the 
anchor  file  descriptors  and  retrie^re  the 
field  that  is  indexed  and  the  anchor  key 
length. 

Head  Index  Descriptors 

DBPac  is  utilized  to  read  seguentially  the 
index  file  descriptors’  and  retrie've  the  index 
key  length  and  the  spanned  indicator, 

Head  Parameter  File 

If  not  the  first  pass,  the  parameter  file  is 
read  to  get  the  needed  key  for  the  restart. 
The  restart  key  is  used  as  the  key  and  a get 
by  key  is  done  on  the  current  index  file, 
also  a read  by  key  is  done  on  the  update  file 
to  find  its  starting  position.  From  here  me 
go  to  normal  reads  on  the  input  files  for 
further  processing. 

Brite  Index  File 

The  *writing  of  the  index  file  can  take  t»o 
different  forms. 

1,  Merge  Inplace, 

If  the  user  decides  to  merge  to  the 
current  index  file  the  new  records  will 
be  built  in  core  and  tabled  there  until 
a unigue  record  is  read.  If  a record  is 
longer  than  the  maximum  allowable 
length,  then  create  a spanned  record. 
Then  rewrite  any  existing  records  and 
write  any  new  records  that  may  have  been 
created.  When  an  update  record  does  not 
match  a current  record,  the  update 
record  and  any  with  the  same  key  are 
written  to  the  current  file, 

2.  Merge  to  Hew  File, 
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The  merge  to  a new  file  is  much  the  same 
as  the  merge  inplace*  The  differences 
are  listed  below: 

a.  in  out  put  file  is  created  with  the 
same  attributes  as  the  current 
index  file. 

b.  There  will  be  no  rewrites  to  the 
new  file. 

c.  All  current  and  update  records  will 
be  written  to  the  new  file. 

g,  Attention  Interrupts 

Attention  interrupt  handling  was  discussed  in 
section  sub-section  ’2',  Item  *B* 

(Write  Parameter  Pile) , 

CODING  SPECIPICATIONS 

1.  Source  language 

The  combine  program  employs  the  lEH  PL/I 

Programming  Language,  The  special  extensions  of 
that  language,  called  DBPl/I  and  TSPL/I,  are 
utilised  for  access  to  file  descriptors  in  the 
data  base  and  for  all  terminal  communication, 
respectively.  Also,  the  merge  program  employs 

assembler  routines  to  handle  all  I/O  during  the 
execution  of  this  program,  except  for  the  writing 
of  the  parameter  file  which  is  handled  exclusively 
by  PL/I. 

2,  Suggestions  and  Techniques 
Not  Applicable 


Figure  1.  I/O  Block  Diagram 
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Figure  2A.  Top  Level  Flowchart 
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TOPIC  D.31  - MSCRIPTOE  EBITOR  - INITIALI  ATIOH 

a.  HODtJlE  NAME 

Program-ID  - BDBEB3N 

, Hodule-ID  ” BBED38' 

B.  ANALYST 

Barry  <3.  Hazl«tt 
Neoterics,  Inc* 

C*  HOBBLE  EUNCTIOH 

This  module  performs  all  of  the  initialization 
necessary  for  the  running  of  the  Descriptor  Editor.  It 
is  called  by  the  Descriptor  Editor  director, 

D,  DATA  HEQUI5EHENTS 

1,  I/O  Bloclc  Diagram 
See  figure  1 

2,  Input  Data  Sets 

a*  Parameter  Cards 
Rot  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

There  are  no  input  files  for  the  Descriptor 
Editor  when  in  the  CREATE  mode  and  the  user 
is  creating  a new  set  of  descriptors* 

, However,  when  in  UPDATE  mode,  or  when  the 

user  is  continuing  the  creation  of  a 
previously  entered  set  of  descriptors,  the 
previously  created  descriptor  file  is  used  as 
an  input  file.  The  description  of  this  file 
is  found  in  the  dataset  specifications  of  the 
DW-B. 

3,  Output  Data  Sets 
a.  Output  Files 

Not  Applicable 
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b.  On  Line  Terminal  Displays 
Not  applicable 
c«  formatted  Print-Onts 
Not  applicable 
4,  Seference  Tables 

Tbe  folloTjing  external  tables  are  referenced  by 
BLEED IB: 

1.  FIELD 

2.  Ft-D 

3.  RDB 

4.  HECSEC 

5.  SECUBITY 

6.  SDPEB 

7.  VALID 

8.  X 

A description  of  these  tables  is  found  in  the 
dataset  specifications  of  the  DWB, 

PBOCESSIBG  BEO.DIEEHENTS 

•1.  Top  Level  Flowchart 

See  Figure  2 

2.-  Narrative 

The  descriptor  file  indicated  is  opened  for  input 
to  determine  if  the'  file  exists.  If  the  file 
exists  and  in  CEEATE  mode,  routine  DBEDID1  is 
called  to  load  the  descriptors.  If  in  DEBATE  mode 
and  the  file  does  not  exist,  the  user  is  given  a 
diagnostic  and  prompted  for  a new  file  name. 

The  verb  table  is  allocated  and  initialized  to  the 
proper  verb  table  copy.  The  routine  DBDSEB  is 
called  to  setup  any  additional  user  defined, 
commands. 

If  in  CREATE  mode  and  no  file  exists,  the  user  is 
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prompted  for  the  anchor  Icey  field,  The  routine 
PEEDAC1  is  called  to  process  and  setup  the  anchor 
Jcey  field. 

The  user  is  prompted  for  the  descriptor  mode*  If 
the  response  is  valid,  flags  are  set  indicating 
the  mode,  and  a pointer  is  set  to  the  appropriate 
verb  table  copy.  If  the  mode  is  invalid,  the  user 
is  given  a diagnostic  and  prompted  for-  a new  mode 
value. 

The  X structure  is  allocated  and  initialised.  The 
initialisation  consists  of  setting  the  various 
pointers  in  X to  nni.1,  . he  FIELD  structure  is 
allocated  and  its  pointers  set  to  NULL, 

If  5EST0EE  mode  is  indicated,  DBEDET  is  -called  to 
restore  the  checkpointed  descriptor.  If  no 
restore  errors  occurred,  the  ■ go  setup  the  verb 
table.  If  there  were  restore  errors,  or  CREATE  or 
OPDATE  mode  were  indicated,  the  file  name  is 
retrieved  from  the  MFCS, 

Control  is  then  returned  to  the  calling  routine,  . 
CODING  SPECIFICATIONS 
1,  Source  Language 

PL/I  "with  DEPL/I  and  TSPL/I  statements 
Suggestions  and  Techniques 
Not  Applicable 


2 


V DESCRIPTOR 
^ TABLES 


Figure  1 . I/O  Block  Diagram 


Figure  2.  Top  level 
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TOPIC  E,  ) - TEHISiUai  SI3PPOET  PBEPEOCESSOB 


A.  BODULE  NAME 

Terminal  Support  IL/I  Preprocessor 
Program-ID  - TSPII 
Hoaule-ID  - TS 

B.  ANALYST 

John  A.  lozan 
Neoterics,  Inc. 

C.  HOPOLE  FUNCTION 


TSPLI  analyzes  terminal  inpnt/output  PX/I  language 
extension  statements  and  produces  statements  acceptahie 
to  the  PI/I  compiler.  These  statements  call  the 
terminal  support  module  allowing  the  program  to 
communicate  with  the  user‘'s  SYSIN  and  SYSOUT  or, 
pending  TSS  support,  an  on-line  display  station.  The 
user's  SYSIN  and  SYSOUT  are  a terminal  if  the  task  is 
conversational,  or  data  sets,  if  non-conversational. 
Diagnostic  messages  are  generated  for  errors  which  can 
be  detected  by  TSPL/I  during  preprocessing. 

D.  - DATA  EEQUIBEHENTS 


1.,  I/O  Block  Diagram 
See  Figure  1 
2.  Input  Data  Sets 

a.  Parameter  Cards 

The  Job  Control  cards  needed  to  invoke,  the 
PI/I  compiler  in  TSS  are  described  in  the 
IBM  TSS/Command  System  User's  Guide,  Form  No. 
C28-200-1 . More  detailed  information  will  be 
provided  in  the  IBH  PL/I  Programmer's  Guide, 
Form  Ho.  C28-2049, 

b.  Punched  Card  Input  Files 
1.  TSPLI  Text 

The  TSPLI  text  d.eck  is  all  text  for 
insertion  into  the  source  program 
following  a »%  INCLUDE  LISBHAC (TS) 
statement  in  the  source  program.  This 
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-text  consists  of  the  source  statements 
of  the  ISPLI  preprocessor  function  and 
any  PL/I  statements  to  he  inserted  at 
the  '•%  INCLUDE  LISEHAC(TS)  statement 
in  the  source  program.  The  TSPLI  text 
is  coded  as  specified  in  this  report, 
formatted  according  to  PL/I  source 
language  standards,  and  catalogued  in  a 
data  set  for  compile  time  use  by  all 
programs  using  TSPLI. 

2.  Source  Deck 

the  source  deck  is  any  PL/I  source 
program  using  TSPLI  statements  to 
interface  mth  the  user*s  SYSIN  and 
SYSOUT  or  any  on-line  display  station. 
The  statement  formats  and  their  use  are 
described  in  the  TSPLI  User’s  Manual 
(Section  8,  Topic  E. 2 of  the  DWB). 

c.  Input  riles 

The  TSPLI  text  statements  are  catalogued  as  a 
member  of  a partitioned  direct  access  data 
■ set  for  retrieval  by  the  IBM  PL/I 
precompiler.  This  data  set  is  accessed  via 
ddname  LISEHAC. 

d.  On-line  Terminal  ‘Entries 
Net  Applicable 

Output  Data  Sets 

a.  Output  Piles 

The  object  module  consists  of  the  relocatable 
machine  instructions  and  constants  generated 
by  the  PL/I  compiler  for  the  source  program. 
It  is  stored  in  a partitioned  data  set.  This 
data  set  is  the  last  DATADEFed  JOBLIB.  If 
the  user  has  not  DATADEFed  any  JOBLIBs,  it  is 
stored  in  the  user’s  USEELIB  data  set.  The 
module  is  loaded  by  TSS  when  called  by  the 
user. 

b.  On-line  Terminal  Displays 
Rot  Applicable 

c.  Formatted  Print-outs 
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1 . 'Precompiler  list-ings 

Two  precompiler  listings  are  produced; 

• (a)  A source  listing  before 
precompilation  and 

(b)  Any  precompiler  diagnostics  (i.e.^ 
errors  in  the  use  of  preprocessor  PL/I, 
not  TSPLI  error  messages)-. 

2.  Compiler  Listings 

The  compiler  listings  produced  include 
an  intermediate  source  listing  (between 
precompiling  and  compiling)  and  any 
compiler  diagnostics.  Serious  TSPLI 
■pl/I  errors  may  result  in  compiler 
diagnostics  also. 

d.  Punched  Card  Output  Files 

Bot  Applicable 

4,  Eeference  Tables 

a.  TC  - terminal  control  block 

h.-  TSPL/I  - diagnostic  comments. 


PBOCESSING  BEQOIREMENTS 

1,  Top  leuel  Flowchart 
See  Figure  2 

2.  Karrative 

a.  Top  level 

The  mainline  PL/I  source  program  is  reguired 
to  have  a IBCLUDF  LISIMAC (TS) ; " statement 
once  in  the  program  before  all  TSPLI 
preprocessor  function  references.  This 
statement  directs  the  PL/I  precompiler  to 
take  text  from  member  TS  of  the  library 
accessed  via  ddname  LISBHAC  and  incorporate 
it  into  the  source  program,  (Befer  to  the 
TSPLI  block  diagram  in  Section  D,1  of  this 
write-up) . 

The  TSPLI  function  receives  one  argument  from 
a preprocessor  function  reference;  i.e«,  a 
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variable  leng-tb  character  string.  It  is 
ISPLI's  function  to  scan  anfl  parse  this  input 
string  to  determine  if  it  is  in  the  correct 
format  and  then  to  generate  a string  called 
the  ” generate a text.”  This  string  consists 
cf  valid  Pl/I  statements  and  comments  for 
commnnication  »ith  the  terminal  support 
modules. 

The  processing  of  TSPX/I  Is  closely  analogous 
to  the  processing  of  DBPl/I  described  in 
Section  17,  Topic  A of  the  .DWB  and  is  only 
summarized  here.  The  TS  text  declares  and 
activates  the  TS  preprocessor  function. 
Argument  initialization,  finding  a 
subargument,  passing  labels  and  comments 
through,  and  finding  the  statement  keyword  to 
select  the  specific  statement  routine  are  all 
done  analogously  to  the  DBPL/I  preprocessor 
function.  Diagnostic  comments  are  generated 
for  any  errors  detected.  {See  Section  III, 
Topic  E.1  of  the  DWB.)  There  are  no  files  to 
be  analyzed. 

In  all  programs  a declaration  of  the  entry 
point  to  the  terminal  support  modules  is 
generated  and  a declaration  of  TC  - the 
Terminal  Control  block  (See  Section  III, 
Topic  E.2  of  the  DWB.) 

Specific  Statement  Routines 

Each  specific  statement  routine  examines  the 
statement  from  left  to  right  until  the 
semicolon  clause  is  found.  The  keywords  are 
verified  for  correct  spelling  and  order.  If 
any  error  is  detected , a diagnostic  comment 
is  generated  and  the  statement  abandoned  by 
control  being  transferred  to  the 
inter-statement  point.  Following  successful 
analysis,  each  specific  statement  routine 
generates  PL/I  statements  for  communication 
with  the  terminal  support  modules  and  loops 
back  to  the  in ter- statement  point. 

The  OW  PAGE  statement  routine  generates  the 
following  statement; 

T C . P A G IH  G_E  STB Y=  ex  press ion ; 

Where  ’’expression”  is  taken  from  the  CALL 
clause  of  the  TS  ON  PAGE  statement. 
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Ihe  ENT-BY  statement  routine  generates  the 
following  statements; 

TS^EHTBY_BE10EN_P0INT=TS_ENTEY_LABEL_n? 
GO  TO  TS_ENTBY_CODING^ 

T?  S_  ENTS  y“i  A BEX_n  ; 

Bhere  "n”  is  a numeric  value  assigneS 
sequentially  to  each  ENTRY  statement  as  it 
is  encountered. 

The  ENSEIE  statement  routine  generates  the 
following  statements; 

DCL  TS_ENTEY_EETDBN  POINT  LABEL; 
TS_ENTEY_EETUEN_POINT=TS__ENTSY_LABEI_1;. 

ts’entey_cobingT 

•ON  CONDITION  (END) 

GO  TO  TS_EXIT_CODING; 

ON  CONDITION  (ATTN) ; 

TC, EUHCTION=*  ENTRY* ; 
can  TSCNTEL(TC)  ; 

GO  TO  TS  ENTEY_RETUEN_POINT; 
TS_EXIT_CODING; 

SETDEN;“ 

TS_ENTEY_iABEL_ 1 ; 

Lines  i|-6  and  10-11  of  the  above  text  are 
only  generated  «hen  the  user  specifies  the 
appropriate  option  on  the  ENABLE  statement. 

The  TS  logic  is  such  that  the  ENABLE 
statement,  if  it  appears,  must  appear  before 
the  first  ENTRY  statement,  and  in  fact, 
implies  an  ENTRY  statement.  Likewise,  the 
first  ENTRY  statement  implies  a default 
ENABLE  statement,  if  none  are  present. 

The  PROMPT  statement  routine  generates  the 
following  statements; 

TC,EDNCTION=*PROHPT-e» ; 

TC . PROMPT. HESSAGE_KEY=expression ; 

TC. PROMPT. KEYNORD=value; 

CALL  TSPBHTe (TC, variable, list) ; 

Bhere  ’’expression"-  is  taken  from  the  MSG 
clause  of  the  statement,  "value"  is  taken 
from  the  KEYNOBD  clause  (if  present) , 
"variable"  is  taken  from  the  INTO  clause  (if 
present)  and  "list**  is  taken  from  the  OSING 
clause  (if  present) • The  value  of  "e"  is 
generated  according  to  the  following  table; 
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1.  INTO  danse  - none 

2,  KEYPOED  danse  - none 
»*e"=C 

3*  KEYEOHD  danse  - yes 
«e”=D 

The  SEAE  statement  routine  generates  the 
follcning  statements? 

TC.EEECTION^'BEAD* ; 

CAIL  TSEEAD(TC, variable); 

Where  "variable”  is  taken  from  the  INTO 
danse  cf  the  TS  EEAD  statement. 

The  WSITE  Statement  routine  generates  the 
foll'owing  statements? 

TC. FDNCTION=* WHITE » ; 

CALL  TSWIITE fTC, variable) ; 

Where  "variable"  is  taken  from  the  PEGB 

clause  cf  the  TS  WHITE  statement*. 

The  POT  statement  routine  generates  the 
following  statements; 

TC.EUHCTION=*POT« ; 

TC. OUTPUT. POSITIOW=*  a* ; 

TC. OUTPUT. DIHECTION=*b» ; - 
CAII  TSPUT (TC, variable, value) ; 

Where  "variable”  is  taken  from  the  EROH 

clause  of  the  TS  PUT  statement  and  "value”  is 
taken  f rcm  the  TAG  clause  (if  present) . The 
value  for  ”a"  will  be  generated  according  to 
the  following  table; 

1.  position  danse  - none 

"a”=0 

2.  position  clause  -XINE 
"a”=0 

3.  position  clause  - PAGE 
«a”=1 

The  value  for  ”b"  will  be  generated  according 
to  the  following  table: 


PAGE  353 


1,  directioix  clause  - none 

2,  direction  danse  - EOBWaED 
"13”=0 

3,  direction  clause  > BACKBAED 

The  EIPSE  statement  routine  generates  the 
foll'oving  statements: 

TC.PDNCT10N=»F1USH»; 
call  TSPIOSB(TC); 

The  EIBISH  routine  sets  a precompiler 
variable  to  indicate  that  a FINISH  statement 
has  been  processed  and  to  prevent  the 
processing  cf  any  further  TSPl/I  statements. 
A diagnostic  comment  indicating  the  number  of 
TSPl/I  errors  is  generated.  If  there  have 
been  any  errors  detected,  the  following 
statement  will  be  generated  causing  an 
IEM0512I  PL/I  error: 

DCL  1S_DUHHY_VABIABLE  LABEL 
INII (TS_ERBS_nn) ; 

Rhere  ’’nn*'  is  the  number  of  TSPL/I  errors 
detected. 

All  statements  and  comments  generated  will  be 
aligned  as  seventy-one  byte  strings,  for  ease 
of  analysis. 


Figure  3.  ! 10  Block  diagram. 


I - ' 
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TOPIC  S,2  - TEEKINAX  SEPPGET  SUPEEVISOE 


A.  HODULE  NAHI 

Terminal  Support  - Terminal  Support  Supervisor 

Program-XD  - RTSUPEE 

Module-ID  - TSUPEB 

Entry  Points  - TSATIN,  TSCNTEL,  TSFXUSH,  TSSETKI, 

TSPEMTC,  TSPRHTD,  TSPBHTK,  TSPUT,  TSBEAD,  ISEEITE 

•B.  AUAIYST 

Frank  Seed 

Seoterics,  Inc, 

C.  HODULE  FUNCTIONS 

1,  Organisation  Chart 
See  Figure  1 

2.  Overview 

RTSUPEE  is  the  primary  vehicle  of  communications 
between  the  NASIS  monitor  (HTT  or  stand-alone) 
and  the.  NASIS  PL/I  data  Base  programs.  Among  the 
functions  RTSUPEE  performs  are: 

a.  Issues  I/O  requests  from  data  base  programs. 
This  includes  command,  data  and  message 
prompts  and  ordinary  read  and  write 
requests. 

b.  Initiali2es  the  Terminal  Control  Block  (TC) 
for  each  PL/I  program.  Supplies  information 
about  the  current  display  area  dimensions  and 
resets  all  bit  switches  to  zero, 

c.  Controls  asynchronous  interrupt  processing. 
Detects  APOFF,  END  and  GO  conditions  and 
issues  that  asynchronous  activities  do  not 
interfere  with  normal  processing, 

d.  Haintains  a push-.down  stack  of  message  key 
references  to  support  the  EXPLAIN  facility, 

e.  Scans  and  passes  user  input  strings  fox 
commands  and  data.  Information  entered  at 
the  terminal  is  interpreted  and  passed  to 
requesting  programs  in  useful  segments.  The 
TC  Block  is  utilized  to  enhance  . interprogram 
communication . 
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D.  PATS  EEQOIEEHEN'TS 

1.  I/O  Block  Diagram 
See  Eigare  2 

2.  Input  Data  Sets 

cl.  Parameter  Cards 
Kct  applicable 

b.  PuncKed  Card  Input  Piles 
Hot  applicable 

c.  Input  Piles 

1.  DBA KIP 

2.  IISBHIP 

d.  On-line  Terminal  Entries 

All  responses  to  command  and  data  prompts  by 
NASIS  pregrams  pass  through  BTSCPEE. 

3.  Output  Data  Sets 

a.  Output  Piles 
Hot  applicable 

b.  On-line  Terminal  Displays 

All  output  from  NASIS  data  base  programs 
passes  through  STSDPEE, 

c.  formatted  Print-Outs 
Hot  applicable 

d.  Punched  Card. output  Piles 
Not  applicable 

4.  Seference  Tables 

a.  External  Tables 

1 , TSCTT 

2,  USEBTAB 

3,  TSCBEEN 

4,  HTTDTAB 
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b.  Internal  Tables 

1 .  EXPX3ST 

An  area  in  which  a push-down  list  of 
message  keys  is  saved, . 

P50CESSIUG  ETQTIIEEHI.NTS 

1.  Top  Level  flowcharts 

a,  aAIKlINE;  See  Figure  3 

b,  Entry  Pcintst; 

1.  TSATIH  - See  Figure  4 

2,  TSCHTRL  - See  Figure  5 

3,  TSFLTJSH  - See  Figure  6 

4.  TSGETKY  - See  Figure  7 

5*  TSPIHTC  - See  Figure  8 

6.  TSPIHTD  - See  Figure  8 

7.  TSPHHTM  - See  Figure  9 

8,  TSPOT  - See  Figure  10 

9,  TSSBITE  - See  Figure  11 

c,  Program  Subroutines: 

1*  GETPB  - See  Figure  13 

2.  DEI-PB  - See  Figure  14 

3.  GETSIN  and  GETDFALT  - See  Figure  15 

4.  FDllBEBD  - See  Figure  16 

5.  SDGlFITi:  and  SDGIVITC  - See  Figure  17 

6.  SDPASS  and  SDYSNCHK  - See  Figure  18 

7.  BESITBUF  - See  Figure  19 

8.  SDSTBIP  and  STBIP  - See  Figure  20 

9.  PEKEYSAV  - See  Figure  21 
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10.  IHCBECK  - See  Eigure  22 

11.  SIGNAL  and  SIGNAIC  - See  Figure  23 
1-2,  -SETIDAB  - See  Figure  24 

13,  GETHLF  - See  Figure  25 

14,  HOVE  - See  Figure  26 

15.  PEOHPT  - See  Figure  28 

16.  EXIT  - See  Figure  29 
2. . Narrative 

a,  KAINLIHE 

All  calls  to  RTSUPEB  entry  points  pass 
through  the  HAIHLINE  code.  The  purpose  of 
this  code  is  to  insure  that  each  user  has  the 
correct  -work-  areas,  to  initialise  base 
registers  and  to  restrict  TS  usage  during 
APOFF  and  ATTENTION  processing. 

Execution  proceeds  by  calling  the  PII  service 
routine  IHESADA  to  obtain  a Dynamic  Storage 
Area  <DSA) ♦ Next,  registers  are  initialized 
and  useful  pointers  are  saved  in  unique 
locations.  The  PII  Pseudo  Register  Vector 
tPRV)  dravs  special  attention  since  it  is  not 
maintained  in  register  12,  as  is  the  norm  for 
other  programs. 

Using  the  PRY,  HAINLINE  determines  if-  a copy 
of  the  TS  Psect  has  been  allocated  for  this 
user..  If  not,  the  routine  GETPR  is  invoked 
to  obtain  one.  On  return,  data  lifted  from 
MTTDTAB  is  utilized  to  compute  the  user*s 
logical  and  physical  device  dimensions  and 
this  information  is  saved  for  future 
reference. 

The  one-byte  switch  lOSN  is  checked  to  find 
out  which  entry  point  was  entered.  If  entry 
was  through  TSATIN,  control  goes  directly  to 
the  interrupt  processing  code.  For  any  other 
entry,  the  contents  of  the  user’s  TC  Block 
{passed  as  a parameter)  is  moved  to  the  DSA 
for  easy  addressability.  If  an  APOFF  has 
been  requested  by  the  user  only  calls  to 
TSPRHTH  and  TSCNTBl  are  allowed  to  execute 
normally,  all  others  being  short  circuited  to 
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the  routine  which  signals  an  END  condition. 

If  not  in  AFOEI  mode,  control  is  passed  to 

the  routine  specified  at  entry. 

Entry  Points 

1.  TSATIN 

This  entry  point  is  called  by  module 
BTSATTN  whenever  it  determines  that  a 
user  attentions  should  be  processed.  If 
the  user  has  previously  entered  APOEP, 
the  attention  is  ignored.  If  an 
immediate  command  is  currently 

processing,  condition  END  is  signaled 
which  terminates  the  command.  If  this 
is  the  second  successive  attention  and 
processing  of  the  first  is  sufficiently 
advanced,  condition  END  is  signaled; 
otherwise,  this  interrupt  is  ignored. 

On  return,  a second  copy  of  the  user 
psect  is  allocated,  the  string  input 
buffer  is  initialised  to  null  input  and 
the  PL/I  routine  EDBATTK  is  called  to 
issue  the  **-ATTN;’*  prompt. 

On  return  from  EDBATTN,  all  user 
requests  have  been  staisfied  and  the 
user  is  ready  to  continue.  After 
closing  the  duplicate  DCBs  for  the 
message  files,  the  duplicate  user  psect 
is  released.  If  the  user  entered  END  or 
APOEI  in  response  to  **-ATTH;**,  then 
pointers  are  set  to  cause  execution  to 
resume  at  the  PL/I  signal  routine  for 
END  condition;  otherwise,  execution 
resumes  at  the  point  of  interrupt. 

2.  TSCNTEL 

Its  function  is  to  initialize  the  TC 
Block  for  use  and  pass  the  user’s 
terminal  dimensions.  Terminal 

dimensions  are  obtained  from  the  user’s 
profile  by  repetitive  calls  to  TSGDEF. 
If  no  defaults  are  specified,  the 
■necessary  information  is  taken  from 
HTTDTAB. 

Control  is  returned  to  the  caller 
through  the  EXIT  routine. 
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•3*  TSELUSH 

TSELUSH  is  the  display  outpat  roatine 
for  terminal  sapport.  It  is  normally 
called  after  consecative  calls  to  TSPOT 
have  caused  an  output  buffer  to  he 
filled.  If  a buffer  has  overflowed  and 
flUTOWEIIE  is  indicated,  this  routine  is 
called  from  TSPUT  and  a flag  is  set  to 
cause  the  **HOEEz’  message  to  replace 
the  next  prompt. 

The  name  of  the  paging  entry  for  the 
program  doing  a PUT  or  FIDSH  should 
always  be  in  the  TC  Block  as  it  is  saved 
by  TSFLUSH  just  prior  to  the  write. 
Data  is  output  one  line  at  a time  for 
typewriters  and  in  a block  for  screens. 
The  most  current  display  is  saved  in  the 
external  controlled  storage  named 
TSCEEES. 

TSGETKY 

This  entry  point  is  called  with  three 
parameters:  (1)  TC  Block,  (2)  message 
key  or  list  reference  or  list  reference 
pointer  in  the  range  -7  < pointer  < o , 
?3)  varying  length  data  area  to  hold  the 
message  text  read  from  the  file.  On 
entry,  pointers  to  these  parameters  are 
plac'ed  in  registers  and  the  type  of 
reguest  is  determined  (either  key  or 
pointer) . 

If  it  is  a pointer,  the  key  is  obtained 
from  EXPIIST  (a  push-down  stack  of 
keys).  If  the  user  wants  just  the  key, 
control  is  returned  to  the  caller. 
Otherwise,  and  if  the  second  parameter 
is  a key,  the  message  file  is  searched 
for  the  Key. 

If  the  key  is  not  found,  error  flags  are 
set  and  control  returned  to  the  caller. 
Else,  the  text  of  the  message  is  read 
into  the  usex*s  area  and  the  message  key 
is  reset  to  point  to  the  next  record  of 
the  file,  if  any,  and  control  is 
returned  to  the  caller. 
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This  is  the  entry  point  called  by  any 
data  base  program  desiring  to  reguest  a 
command  from  the  user. . On  entry,  and 
internal  buffer  is  checked  for  the 
■presence  of  a previously  entered 
command.  If  one  is  there,  it  is 
returned  to  the  caller  as  satisfying  the 
prompt.  If  the  buffer  is  empty,  a 
message  key  passed  as  a calling 
parameter  is  used  to  access  a message 
file  to  obtain  the  text  of  the  message 
which  describes  the  context  of  the 
prompt  to  the  user.  This  message  is 
displayed  in  the  prompt  area  of  ' the 
user's  I/O  device  and  the  terminal’  is 
opened  for  input. 

The  response  to  this  prompt  must  be  a 
command.  It  may  be  the  one  requested  by 
the  calling  program,  in  which  case  it  is 
passed  along.  Or,  alternatively,  it  may 
be  any  of  the  * 'immediate* * commands 
which  cause  one  of  the  immediate  command 
processors  to  be  invoked.  After  all 
activities  associated  with  the  immediate 
command  are  completed,  the  execution 
cycle  beginning  on  enty  to  TSPBHTC  is 
repeated  until  a satisfactory  response 
is  returned  to  the  caller  or  until  APOFE 
or  END  processing  is  initiated. 

Consult  the  Command  System  User's  Guide 
for  details  of  command  syntax, 

TSPRHTD 

This  entry  point  is  called  by  a data 
base  program  wishing  to  obtain 
user-entered  data.  On  entry,  the. save 
internal  buffer  that  holds  commands  is 
checked  for  a parameter  string  that  may 
have  been  entered  with  a command.  If 
data  is  there,  it  is  passed  out  of  the 
string  (in  accordance  with  the  syntactic 
unless  outlined  in  the  Command  System 
User's  Guide)  and  returned  to  the 
calling  program.  If  the  buffer  is  empty 
or  the  next  item  in  it  is  a command,  a 
message  key  passed  as  a calling 
parameter  is  used  to  access  a message 
file  to  obtain  the  text  of  the  message 
which  will  explain  to  the  user  what  data 
is  requested.  The  message  is  displayed 
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in  the  prompt  area  of  the  user*s  I/O 
device  and  it;  is  opened  for  input,  . 

The  response  to  this  prompt  may  be-  data 
or  any  of  the  immediate  commands.  If  it 
is  data,  it  is  passed  as  above  and 
returned  to  the  user.  The  terminal 
Control  Block  sewer  as  a center  for 
communicating  information  about  the  data 
between  TSPBKTB  and  its  caller.  , 

If  the  response  is  an  immediate  command, 
this  command  and  its  associated 
parameters  are  treated  separately  from 
any  user  input  intended  for  a data  base 
program.  ?hen  processing  of  the 
immediate  command  is  complete,  the  cycle 
beginning  on  entry  to  TSPHMTD  is 
repeated  until  a satisfactory  response 
is  received  or  until  APOEE  or  END 
processing  is  initialed. 

Consult  the  Command  System  User’s  Guide 
for  the  details  of  parameter  syntax. 

TSPBHTH 

This  entry  point  is  called  to  display  a 
message  from  IISBMIF  on  the  user’s 
terminal.  No  -reply  is-  asked  for. 
Auxiliary  subroutine  entry  points  are 
called  from  various  locations  in  HTSDPEE 
to  perform  prompting  tasks. 

The  message  filter  HSGIEVEL  in  the 
user’s  profile  determines  wether  or  not 
informational  (I-level)  messages  are 
displayed,  Naming  (W-level)  messages 
are  always  transmitted. 

The  message  ID  filter  HSGIDS  specifies 
insertion  of  the  message  key  between  the 
message  prefix 'and  the  text,  HSGIDS=*Y 
reguests  display  of  message  keys, 
HSGIDS=N  implies  no  keys. 

If  the  last  output  to  the  display  area 
left  residual  data  undisplayed,  the 
’’KOBE’’  message  is  substituted  for  any 
command  or  data  prompt  message.  The  key 
of  every  message  (except  explanations) 
is  placed  in  the  EXPIIST  area  for 
reference  by  the  EXPLAIN  command. 
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8.  T-SPUT 

3SFDT  may  be  called  one  or  more  times  by 
data  base  programs  to  format  data 
(passed  as  a parameter)  In  a buffer  for 
output.  The  data  consists  of  a string 
of  characters  to  be  displayed  on  the 
user’s  terminal  and  an  optional  tag 
field  which  is  appended  to  the  beginning 
of  the  string*  Eormatting  consists  of 
manipulating  the  data  so  that  it  appears 
in  a consistent  and  logical  pattern  on 
the  screen. 

On  entry,  TSPUT  initializes  pointers  and 
work  areas  based  on  whether  a restart, 
continuation  or  backwards  put  is 
indicated.  After  insuring  there  is 
sufficient  room  in  the  buffer  to  insert 
new  data,  a subroutine  is  called  to  move 
the  tag  and  data  string  to  the  output 
buffer.  This  step  is  repeated  until  all 
data  is  in  the  buffer  or  the  buffer  is 
filled.  An  attempt  is  made  to 
terminate  lines  between  words  and  at 
punctuation. 

On  buffer  overflow,  if  the  caller  does 
not  want  overflowed  records  inserted, 
all  pointers  are  reset  and  control  is 
returned  to  the  caller.  If  partial 
records  are  inserted,  control  characters 
are  appended,  a TC  Block  variable  is  set 
to  indicate  the  number  of  characters 
taken  and  the  AOTOWSITE  switch  is 
checked.  If  it’s  on  control  passes  to 
the  ELDSH  routine,  otherwise  control  is 
returned  to  the  caller. 

If  all  data  is  inserted  with  no 
overflow,  the  trailing  position  of  the 
record  is  padded  with  blanks  (to  fill 
out  a screen  line)  and  control  is 
returned  to  the  caller, 

9.  TSWEITE 

This  routine  is  called  to  flush  the 
contents  of  the  external  storage  named 
TSCBEER.  After  locating  the  area 
control  is  passed  to  EIUSB,  which 
outputs  the  data  and  returns  control  to 
the  caller. 
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Subroutines 

-1.  GEIFE 

This  routine  calls  the  PL/I  controlled 
storage  allocation  routine  **IHESADD** 
to  obtain  space  into  uhich  the  master 
I>S6Ct  may  be  copied.  The  caller’s 
registers  are  saved  in  area  common  to 
the  copy  routine  so  after  the  area  is 
obtained  a branch  is  taken  to  MOVECOPY 
and  from  there  control  is  returned  to 
the  caller. 

2.  DELPB 

This  routine  simply  deallocates  the 
external  controlled  storage  allocated  by 
GETFl.  The  PI/I  service  routine 
’’IHESAFF**  is  called  to  perform- this 
function. 

On  return,  register  12  is  set  to  point 
to  the  next  area  in  the  chain  and 
control  is  returned  to  the  caller, 

3,  GETSYU  and  GETDFAIT 

These  two  subroutines  primarily  the  save 
code,  the  differences  being  in  the 
lengths  of  the  parameter  list  used  in 
the  eventual  call  to  an  external  program 
and  the  v-core  which  is  posted  in 
register  15  and  points  to  the  program 
which  is  called,  GETSYN  calls  TSGSYN  to 
obtain  a synoyra  for  a term.  GETDFAIT 
calls  TSGDEF  to  obtain  a default  value 
for  a parameter.  On  return  from  the 
respective  calls,  the  length  of  the 
' returned  data  is  checked.  If  nothing 
came  back,  the  data  pointers  are  reset 
to  point  to  the  data  used  as  a calling 
parameter. 

i|.  PULIHEND 

This  subroutine  is  called  by  TSPDT  to 
insert  the  proper  end-control  characters 
on  each  line  of  display  output  as  it  is 
moved  into  the  output  buffer.  Screen 
lines  are  padded  with  blanks  to  fill  out 
the  line.  Typewriter  lines  are 
terminated  with  an  interpretive  hex 
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15, 


5.  GIVIITD  ana  GIVITC 

These  tnfo  subroutines  are  called  by  the 
prompting  xontine  to  pass  data  to  the 
tiser.  If  the  prompt  processing  is  in 
skip  mode  ox  the  call  was  inadvertently 
done  before  an  item-was  found,  the  pass 
is  not  done.  Otherwise  SDPASS  is  called 
to  move  the  data  to  the  user’s  area. 

On  return,  the  passed  data  is  excised 
from  the  input  buffer.  If  it  came  from 
a parenthesized  list,  the  list  flag  is 
set  in  the  terminal  Control  Block  and 
control  is  returned  to  the  user, 

6.  SDPASS 

SDPASS  compares  the  length  of  the  data 
or  command  passed  from  the  input  string 
with  the  receive  area.  If  the  item  will 
fit  the  area,  it’s  moved,  otherwise  a 
syntax  error  is  noted  and  error 
processing  is  begun, 

7,  SDSINCHK 

This  routine  is  called  to  check  for 
certain  syntax  errors.  If  an  error  is 
detected,  control  is  transferred  to 
SINSEB  to  initiate  an  error  control 
sequence.  Otherwise,  control  is 

returned  to  the  point  of  call. 

8,  BESITBUP 

Preparing  a buffer  for  input  and 
initializing  all  flags  associated  with 
input  passing  is  performed  here, 

8.  SDSTBIP  and  STBIP 

SDSTEIP  is  called  to  delete  leading  and 
trailing  quotes  and  leading  and  trailing 
blanks  from  an  item  passed  as  input  to  a 
calling  program.  If  only  blanks  are  to 
be  deleted,  entry  is  at  STRIP, 

10,  PBKEYSAV 

Inserts  the  key  of  a prompting  message 
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into  a posh-down  list  of  message  keys 
for  reference  by  the  EXPLAIN  command, , 

11.  IHCHECK 

Whenever  the  user  enters  an  immediate 
command,  it  is  discovered  by  this 
snbroutine.  Comparing  the  entered 
command  against  a table  of  valid 
immediate  commands,  a *^hit'*  leads  to 
either  signalling  **ENI)**  or  calling  an 
external  program  to  initiate  processing. 
On  return,  the  prompt  routine  is 
informed  of  the  occurrences  and  the 
prompting  cycle  begins  again. 

12.  EIGNAl  and  SIGNALC 

Entry  at  SIGNAL  causes  preparations  to 
call  the  PL/I  service  routine  IHBEEED. 
Control  then  falls  through  to  SIGNALC, 
which  calls  a pre-indicated  routine  and, 
on  return,  itself  returns. 

13.  SEflDBA 

This  routine  opens  and  initialises  the 
DCBs  for  the  prompt  message  libraries. 
Also,  it  issues  a SETL  to  find  a 
particular  message  key — ^in  the  file. 
Hember  LISSHLF  of  DBALIB  is  searched 
first,  followed  by  member  LISHHLF  of 
IISBLIB.  If  the  Key  is  not  found  in 
either  DBALIB  or  LISELIB,  a substitute 
message  is  written  which  indicates  the 
message  was  not  found. 

14.  GETKLF 

Its  function  is  to  read  the  text  of  a 
message  record  pointed  to  by  a message 
key.  Each  record  read  is  check  for  the 
prescence  of  a minus  sign  {-)  or  plus 
sign  (+)  is  its  last  character. 

If  there  is  a minus  sign,  the  next 
-record  is  read  and  appended  to  the 
first.  If  the  last  is  a plus  sign,  the 
truncation  bit  in  the  TC  Block  is  set  to 
one(1)  and  control  is  returned  to  the 
caller. 
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All  extended  data  relocations  are 
performed  by  this  routine.  In  addition 
it  is  also  used  to  blank-fill  a data 
area  and  copy  from  one  area  . to 
another, 

16,  PEOaPT 

On  entry,  if  the  user  is  in  SESTABT  or 
SEEON  mode  the  next  record  of  input  is 
obtained  from  the  strategy  dataset  named 
in  the  external  control  block  ‘ USERTAB, 
Otherwise  pointer  and  constants  are  set 
in  the  I/O  control  block  and  MTT  is 
called  to  do  an  I/D. 

On  return  from  ail,  the  return  code  in 
register  15  is  checked.  If  there  was  an 
error,  attention  interrupt  or 

continuation  the  I/O  is  retried, 
otherwise,  the  data,  is  moved  to  a work 
area  and  control  is  returned  to  the 
caller, 

17.  EXIT 

Beturning  to  any  program  calling  an 
BTSDPEB  entry  point  is  accomplished  by 
passing  through  this  code.  The  caller’s 
TC  Block  is  updated  by  moving  cur  copy 
of  it  back  into  the  cailer’s  area.  The 
PHV  is  restored  in  register  12  and 
control  is  returned  by  calling  the  PL/I 
service  routine  IHESAPA  which  releases 
our  Dynamic  Storage  Area  (DSA)  and 
restores  the  callers  registers, 

CODING  SPECIFICATIONS 

1,  Source  language 

TSS/360  Assembler  Language, 

Suggestions  and  Techniques 

Not  Applicable 
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Figure  1.  Teraiiial  Support  Organization  Chart 
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Figure  6.  Entry  Point  TSFLUSH 


Figure  7,  Entry  Point  TSGETKY 


TSPRMTD 


TSPRirrC 


276 


SAVE 

STARTING 
SCAN  ; •: 
POINTERS 


Z11 


SCAN 

STRING 

FOR 

DELIMITERS 


SET 

FLAGS  AND 
SWITCHES 


COMPUTE 
LENGTH  OF 
ITEM  FOUND 


Figure  8A.  Entry  Points  TSP5MTC  and  TSPRMTD 
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Figure  8B.  Entry  Points  TSPSMTC  and  TSPEMTD 
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Figure  8D.  Entry  Points  PSPRMTC  and  TSPRMTD 


Figure  8E-  Entry-Points  TSPEHEC  and  TSPRMTD 
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Figure  lOA.  ‘ Entry  Point  TSPUT 


Figure  11.  Entry  Point  WRITE 


Figure  13 


Subroutine  GETPR 


Figure  14.  Subroutine  DELPR 


Figure  16.  Subroutine  PULINEND 


Figure  17.  Subroutines  SDGI?ITB  and  SDGI7ITC 


Figure  19 


Subroutine  RESETBUF 
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Figure  20.  Subroutines  SDSTRIF  and  STRIP 
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Figure  21 


Subroutines  ERKEYSAV 


Figure  22.  Subroutine  IMCHECK 
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Figure  23 


Subroutines  SIGNAL  and  SIGNALC 


Figure  28 


Subroutine  PROMPT 
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TOPJC  E.3  - PLI/ASSEHBLEE  IIBKAGI  MOBOLE 

A, ..  MODULE  MAME 

Program-ID  - EDBPLISK 
Module-ID  - DBPLIKK 

B,  AKALYST 

John  A.  Lozan 
Neoterics,  Inc* 

C,  MODULE.  PUSCIION 

Ihis  module  completes  the  linkage  between  a Pl/I 
program  and  an  assembler  subroutine.  It  does  so  in 
such  a way  that  the  assembler  routine  may  in  turn  call 
a PL/I  subroutine  and  yet  maintain  the  continuity  of 
control  necessary  for  proper  PL/I  linkage  and 
communication.  Another  aspect  of  the  linkage  method  is 
that  it  not  only  makes  the  module  reentrant,  from  an 
HTT  standpoint,  but  also  recursive, 

D,  DATA  EEQUIBEMESTS 

1,  I/O  Block  Diagram 
Bot  Applicable 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punchea  Card  Input  Piles 
Not  Applicable 

c.  Input  Piles  • 

Not  Applicable 

d.  On~line  Terminal  Entries 
Not  Applicable 

3,  Output  Data  Sets 
a.  Output  Piles 

Not  Applicable 


Figure  29.  Subroutine  EXIT 
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b.  On-line  Terminal  Displays 
■Rot  applicable 
c«  Tormatted  Print-Onts 
Rot  applicable 

a*  PancHed  Card  Output  riles 
Sot  Applicable 
4.  Seference  Tables 
Hot  applicable 

E,  . PSOCESSIHG  EEQUIEEMENTS 

1*  Top  level  Flowchart 
See  Figure  1 
2.  Narrative 

Upon  entry,  the  program  initializes  the  variables 
it  needs  from  the  parameter  list  passed  by  the 
calling  module.  This  data  is  used  to  obtain  from 
Pl/I  library  routine  IHESaDA  a dynamic  storage 
area  (DSA)  large  enough  to  contain  the  register 
save  area  and  a copy  of  the  calling  routine’s 
psect. 

Once  this  has  been  done,  the  program  copies  the 
calling  programs  PSECT  to  the  DSA,  chains  the  DSA 
into  the  pseudo  register  vector  (PSV)  and  posts 
the  DSA  address  in  register  13.  The  program  then 
initializes  all  of  the  base  registers  regui-red. 

Before  exiting  the  program  restores  the  remaining 
registers  from  the  calling.  programs  caller’s 
savearea.  It  then  chains  the  DSA  into  the 

savearea  chain  and  returns  to  the  caller." 

F.  CODING  SPECIFICATIONS 

1,  Source  Language 

The  module  is  written  using  the  TSS  360  Assembler 
language, 

2.  • Suggestions  and  Techniques 

Extreme  care  must  be  taken  to  ensure  the  fact  that 
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this  program  is  completely  reentrant  and 
recursive,  all  operations  should  be  performed  in 
registers,  or  in  the  DSA  obtained  from  Pl/I. 


Figure  1.  Top  Level  Flowchart  - DBPLINK 
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TOPIC  E.  4 - ASYNCHEOUOUS  INTEBBXJPT  PBOCESSOB 


A,  MODOLE  BAHI 

Terminal  Support  - Attention  Interface 
Program-I'D  - BTSATTM 
Module-ID  - TSATTN 
Entry  Point  - TSflATTN 

B,  AKAIXST 

Prank  Seed 
Neoterics,  Inc. 

C,  MODULE  EUNCTIONS 

1.  Organization  Chart 
See  Figure  1 

2,  - Overview 

BTSATTM  is  the  interface  tetueen  whatever. monitor 
is  running  <HASIS  or  NASISX)  and  the  terminal 
support  supervisor  BTSDPEB.  Its  function  is  to 
link  the  monitor  to  the  BTSDPEB  attention  routine 
TSATIH.  BTSATTH  is  only  called  after  are 
asynchronous  interrupt  resulting  from  the  user 
depressing  the  attention  key  at  his  terminal, 

D,  . DATA  BEQOIBEHENTS 

Not  Applicable 

E,  PHOCESSIWG  BEQDIIEMENTS 

1,  Top  level  Flowchart 
See  Figure  2 

2.  Narrative 

On  entry,  HTSATTN  performs  TSS  standard  linkage 
except  that  the  address  it  picks  up  as  its  PSECT 
register  points  to  a table  of  r-cons  which  are  <in 
order) : TSATIN  and  HTTDTAB.  TSATIH  is  the  entry 

point  to  terminal  Supports*  attention  processing 
routine  HTTUTfiB  is  a table  which  holds  the  user’s 
pseudo-register  vector  (PB7) • 

After  linking,  BTSATTH  checks  the  interrupted 
register  13  to  determine  if  it  points  to  a PI/I 
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Dynamic  S-torage  Area  (DBA)  • If  not,  no  further 
attempt  is  made  to  process  the  attention.  That 
is,  ETSATTN  returns  to  the  monitor,  effectively 
ignoring  the  Interrupt, 

^Ihen  a valid  BSA  is  found,  the  PE7  is  checked  and 
if  it  is  OK  the  DSA  registers  are  saved  in  an  area 
provided  by  the  monitor,  ETSATTN  next  calls 
TSATIN  using  the  interrupted  DSA  as  a savearea. 

On  return  frcm  TSATIN,  the  DSA  regs  are  restored, 
the  caller's  registers  are  restored  and  control  is 
returned  to  the  monitor. 

CODING  SPECIFICATIONS 

1,  Source  language 

TSS/360  Assembler  Language, 

2,  Suggestions  and  Techniques 

The  NASIS  assembler  macro  library  ESOUECE  must  be 
used  to  reference  the  User  Information  Table 
(ETSUTAB) . Also,  entry  linkage  is  standard 
TSS/360  while  calling  linkage  is  standard  PL/I, 


Figure  1.  Terminal  Support  Organization  Chart 
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TOPIC  E,5  - ATTEHTICW  SiOHSTIUG  SIOGEAH 
A.  HODDLE  NAME 

Terminal  Support-Attention  Prompting  Program 
Program-ID  - BDBATTN 
Hodule-ID  - DBATTN 
Entry  Point  - DBATTM 

B*  ANALYST 

Prank  Beed 
Neoterics,  Inc. 

C.  HODDLE  PDNCTIONS 

1,  Organization  Chart 
See  Figure  1 
-2.  Overview 

DBATTN  is  called  by  BTSDPEE  to  issue  the  command 
prompt  **-ATTN;**  and  check  the  user’s  response 
thereto. 

D.  DATA  REQDIBEMEHTS 

1.  I/O  Block  Diagram 
Not  Applicable 

2.  Input  Data  Sets 
Hot  Applicable 

3.  Output  Data  Sets 
Not  Applicable 

4.  Seference  Tables 

a.  External  tables 
LISRHAC  (DSEETAB) 

b.  Internal  Tables 
Not  Applicable 

E.  PROCESSING  REQUIREMENTS 
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1,  Top  Level  Plovchart 
See  Pig ore  2 

2,  narrative 

On  entry,  DBATTH  checks  the  DISABLED  switch  in 
USEETAB,  If  attentions  have  been  disabled, 
TSPEMTH  is  called  to  inform  the  user  at  the 
terminal  and  execution  returns  to  the  caller.  If 
attentions  are  enabled,  DBATTN  sends  a blank 
character  out  to  insure  that  the  carriage  is  in 
its  heme  position,  then  issues  a command  prompt 
vith  the  message  **-ATTN;**  to  allow  asynchronous 
commands  to  be  entered  by  the  user. 

STSUPEE  intercepts  all  * ’iraraediate’ * commands 
except  GO  and  calls  the  appropriate  routine.  If 
the  user  enters  GO,  null  or  any  non-immediate 
command,  DBATTN  takes  the  following  action: 

a,  GO  or  null  - returns  control  to  the  caller, 
thus  signifying  the  end  of  the  prompting 
sequence. 

b*  Ncn-imroediate  command  - ignores  the  user*s 
response  and  reprompts  as  above. 

If  the  END  condition  is  raised  while  executing 
this  module,  execution  control  is  returned  to  the 
caller, 

CODING  SPECIPICATIONS 
1.  Source  language 
TSS/360  Pl/I 

Suggestions  and  Techniques 
Hot  Applicable 


2 


Figure  1.  Terminal  Support  Organization  Chart 
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TOPIC  F.1  - EETHIEVAX  1NITIALI2ATI0H 

A.  0ODOLE  NAHEz 

Program-ID  - REBINIT 
Hoaale-ID  - DBINIT 

B.  ASAXTST 

John  A,  lozan 
Neoterics,  Inc. 

C.  0ODU1E  FUNCTION 

This  raoSnle  performs  the  initialization  functions  for 
the  retrieval  sjstera  and  is  the  command  director 
^prompting  module)  for  retrieval, 

B.  DATA  EEQUIBEHENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a,  . Parameter  Cards 

Not  Applicable 

b.  Punched  Card  Input  Files 
Hot  Applicable 

C,  Input  Files 

Hot  Applicable 

d,  On-Line  Terminal  Entries 

The  program  initially  prompts  for  the  FILE, 
BABE  and  ADDRESS  parameters,  and  later, 
prompts  for  the  retrieval  commands, 

3.  Output  Data  Sets 

a.  Output  Files 
Hot  Applicable 

b,  On-Line  Terminal  Displays 
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The  program  issues  various  diag.nostic 
messages,  where  appropriate. 

c,  lormattea  Print-Outs 
Pot  Applicable 

d.  Punched  Card  Output  Piles 
Hot  Applicable 

4,  , Beference  Tables 

The  program  references  and  optionally  initializes 
the  fcllowing  tables, 

DSEBTAE 

FIDTAE 

COLFOEH 

SEQFOIH 

SECHTAB 

VEEETAE 

RETDATA 

SETAE 

E.  PROCESSING  REQUIEEEEHTS 

1.  TOP  XEVEI.  FXCRCHART 
See  Figure  2 

2.  Narrative 

It  calls  DBJOIND  to  process  the  file  parameter  and 
prompts  for  the  HAHE  and  ADDRESS  parameters.  The 
parameters  are  all  verified  and  saved  for  later 
reference. 

The  program  then  defines  the  print  data  set  and 
the  save  data  set  and  initializes  the  retrieval 
data  table,  EETDATA.  The  set  table,  SETAE  is  then 
initialized,  the  data  base  is  opened  for  input  and 
the  field  table,  FIDTAB,  is  initialized. 

The  . program  then  initializes  its  verb  table, 
including  the  addition  of  any  user  defined 
commands.  New  the  program  prompts  the  user  for  a 
retrieval  command. 

If  the  command  entered  was  not  END  or  BEGIN,  the 
program  calls  the  entry  point  specified  for  that 
command  and  than  branches  back  to  prompt  the  user 
for  his  next  command. . If  the  user  entered  END  or 


PAGE  416 


BEGIH,  the  retrieval  session  is  terminated  by 
closing  the  data  base,  erasing  the  sets,  the 
formats  and  the  save  data  set.  The  print  data  set 
is  printed.  All  searches  are  cancelled.  If  the 
user  entered  BEGIN,  the  program  branches  back  to 
initialize  itself  for  a new  retrieval  session. 
Otherwise,  the  program  is  terminated, 

CODING  SPECIIICATIGNS 

*1,  Source  Language 

The  module  is  written  using  the  TSS  360 ‘ PL/I 
language, 

2,  Suggestions  and  Techniques 
Not  Applicable 
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TOPIC  F.2  - PETBIlVAl  JIEI.DS  COHHAND 

■A,  HODPLE  UAHE 

Program-ID  - EDBEIBS 
J3oa«le-ID  - DBEXDS 

B.  iNAlYST 

John  A.  lozan 
Neoterics,  Inc, 

C.  aODULE  FUNCTION 

This  module  displays  a formatted  listing  of  the  field 
names  of  the  file  currently  being  accessed  by  the 
user. 

D.  BATA  BEQDIEEHENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Bata  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Piles 
Not  Applicable 

c.  Input  Piles 
Not  Applicable 

d.  On-X’ine  Terminal  Entries 

The  routine  prompts  for  the  parameter 
associated  «ith  a PAGE  command, 

3,  Output  Data  Sets 

a,  ’Output  Piles 
Hot  Applicable 

b.  On-line  Terminal  Displays 

The  program  produces  a formatted  list  of 


PAGE  420 


field  name, 

c,  Eormafted  Print  Outs- 
Hot  Applicable 

d.  PuncEed  Card  Output  Files 
Kot  Applicable 

4,  Beference  Tables 

FIDTAE-The  program  extracts  all  of  its  information 

from  FLbTAB» 

E.  PROCESSING  REQUIEEHENTS 

1,  Top  Level  Flowchart 

See  Figure  2 

2.  Narrative 

a.  EBFLDS 

At  this  entry  point  the  program  initializes 
the  screen  and  paging  status  data.  It 
extracts  the  data  base  name  from  FLDTAB,  The 
program  then,  repetitively,  extracts  the 
field  names  from  FXDTAB,  It  flags  each  field 
that  has  an  inverted  index.  It  posts  the 
field  names  to  the  screen.  When  the  list  of 
=names  has  been  exhausted,  or  the  screen  has 
been  filled,  the  screen  is  displayed  to  the 
user,  the  paging  status  data  is  posted  and 
the  program  is  terminated. 

b.  EBTIDSP 

At  this  entry  point  the  program  is 
re-initialized  using  the  paging  status  data. 
If  more  data  remains,  the  program  branches  to 
the  proper  routine  to  build  the  next  screen 
image.  Otherwise,  a diagnostic  message  is 
written  to  the  user  and  the  program  is 
terminated, 

F.  CODING  SPECIFICATIONS 

1.-  Source  Language 

The  module  is  written  using  the  TSS  360  PL/I 

Language. 


Suggestions  and  Techniques 
Not  Applicable 
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TOPIC  E.3  - BETEIEVAl  EIPAUD  COKHAND 

-A.  aODTJLE  .SAME 

Program-ID  - EDBXPND 
Soaule-ID  - DBXPND 

B.  AUALYST 

Jolm  A*  Lozan 
■ffeoterics,  Inc, 

C.  HODOLE  EONCTION 

This  module  displays  to  the  retrieval  user,  a formatted 
listing  of  a cross  section  of  an  inverted  index 
surrounding  a specified  term, 

D.  . DATA.  EEQUIEEHENTS 

1,  I/O  Block  Diagram 
See  figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Rot  Applicable 

b.  Punched  Card  Input  Piles 
Not  Applicable 

c.  Input  Piles 

The  inverted  index  files  of  a dataplex  are 
used  as  a source  of  data  by  the  program, 

d.  . On-Line  Terminal  Entries 

The  program  prompts  for  the  TEBH  and  INDEX 
•parameters, 

3,  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b,  On-Line  Terminal  Displays 
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The  program  prodtices  a formatted  listing  of 
the  index  records  read. 

c,  Pcrmatted  Print  Outs 
Not  Applicable 

d.  Punched  Card  Output  Piles 
Not  Applicable 

4,-  Reference  Tables 

The  program  uses  the  following  tables  as  a source 
of  data  and  as  a means  of  data  control, 

USEETAB 

PLDTAB 

EXPTAE 

PROCESSING  REQBIREKSHTS 

1.  Top  leuel  Plowchart 
See  figure  2 

2,  Narrative 
a.  EBSPNP 

At  this  entry  point  the  program  initializes 
itself  to  perform  a new  expansion  of  an  index 
file.  The  program  initializes  the  screen  and 
the  data  storage  table  EXPTAB. 

The  program  then  prompts  the  user  for  the 
TERM  and  INDEX  parameters.  The  parameters 
are  validated  and  the  program  gets  ready  to 
read  the  index  (or  anchor)  file  specified. 
The  first  read  of  the  file  is  for 
positioning,  based  upon  the  term  entered  by 
the  user.  The  program  then  attempts  to  read 
the  previous  three  records  in  the  file.  As 
each  record  is  read  the  term  is-  posted  into 
EXPTAB  along  with  the  number  of  cross 
references.  The  relative  E-number  is 
computed  and  is  also  posted. 

If  more  space  remains  on  the  screen  and  more 
data  remains  on  the  file,  the  program 
positions  itself  and  begins  reading  records, 
saving  the  data  in  EXPTAB  and  posting  them  on 
the  screen.  If  an  end-of-file  is 


PaGE  426 


encotmtered,  an  Indication  is  posted  on  the 
screen.  it  this  point,  or  when  the  screen  is 
filled,  it  is  displayed  to  the  nser,  the 
paging  status  data  is  posted  and  the  program 
terminates. 

• If  any  errors  are  encountered,  a diagnostic 
message  is  written  to  the  user  and  the 
program  is  terminated, 

b,  EEXPUDP 

at  this  entry  point  the  program 

re- initializes  itself  using  the  paging  status 
data.  If  more  data  remains  to  be- displayed 
the  program  branches  to  the  appropriate  point 
to  begin  reading  the  index  and  building  the 
new  screen  image.  If  no  more  data  remains,  a 
diagnostic  message  is  written  to  the  user  and 
the  program  is  terminated, 

c.  EBXPUBE 

Bt  this  entry  point  the  program  initializes 
itself  to  decode  an  E-number  reference.  If 
the  E-number  parameter  is  valid,  the  data 
associated  with  it  is  passed  back  to  the 
caller.  Otherwise,  an  error  indicator  is 
. passed  back  to  the  caller  and  the  program  is 
terminated, 

CODING  SPECIFICailONS 

1.  Source  language 

The  module  is  written  using  the  TSS  360  - Pl/I 
language, , 

Suggestions  and  Techniques 

The  BEEA  facilities  of  Pl/I  should  be  used  to 
organize  the  term  data  stored  in  EXPTAB  to' 
optimize  file  access  and  data  storage. 
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TOPIC  P.4  - SETHIE7A1,  Select  CoBmaud 
I. . SELECT 

A,  MOBOLE  EAHE 

Betrieval,  SELECT  Command 
Program  - IB  - BDBSLCT 
Hodule  - IB  « BBSLCT 

Entry  Points  (DBSXCT0,BBS1CT1,DBSLCT2) 

B,  AWAIIST 

0.  Kirt  fiearne 
Neotericsi-'  Inc. 

C,  HODULE  PUBCTIOH 

The  SELECT  ccmmand  format  is; 

SELECT  expression  r field , replace , method 

The  SELECT  ccmmand  outputs  the  expression  and,  the 
number  of  citations  (record  keys)  for  which  the 
expression  applies.  A set  number  or  S-number  is 
assigned  to  the  expression,  and  the  command  string 
is  entered  into  the  next  available  line  in  the 
cnrrent  search  strategy. 

The  expression  parameter  (keyword=EXPB)  is  a 
boolean  combination  of  terms  which  define  a set. 
If  all  fields  referenced  are  indexed,  the 

expression  is  evaluated  immediately  and  a 
set-number  assigned.  If  a field  in  the  expression 
is  not  indexed  or  a previous  S-number  is 

referenced,  a search  entry  is  constructed  and 
saved,  and  an  S-number  assigned. 

Only  a single  non-indexed  field  is  allowed  in  a 
single  SELECT  expression. 

The  field  parameter  {keyword=PIELD)  is  used  by 
SELECT  to  resolve  any  values  in  the  expression 
which  are  not  directly  related  to  a fieldname 
within  the  expression. 

The  replace  parameter  (keyword=EEPLACE)  is  a 
previously  defined  S-number  which  is  to  have  its 
expression  replaced  by  the  current  expression. 

The  method  parameter  (keyword=HETHOB)  is  used  to 
force  a search  on  indexed  fields.  To  do  this, 
"SEAECH”  must  be  entered  as  the  method  parameter. 
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note  that  only  a single  field  may  be  referenced  in 
this  case* 

SELECT  will  prompt  the  user  if  the  expression  is 
missing,  ox  the  field  parameter  is  missing  and 
found  to  he  needed* 

DATA  BEQDIBEaENTS 

1.  I/O  Block  Diagram 

See  Eigure  1 

2*  Input  Data  Sets 

a*  Parameter  Cards 

Not  Applicable 

h*  Punched  Card  Input  Files 
not  Applicable 
c.  Input  Files 

The  descriptor  files  and  the  index  files 
may  be  referenced  by  the  SELECT  command. 
The  descriptor  file  is  used  to  obtain 
the  data  set  name  of  the  subject  term 
index  file.  The  index  files  are  used  to 
obtain  a list  of  accession  numbers 
associated  with  a particular  subject 
term, 

d*  On-line  Terminal  Entries 
Not  Applicable 
3,  Output  Bata  Sets 
a*  Output  Files 

The  command  string,  as  it  is  entered,  is 
saved  in  the  region  containing  the 
current  strategy  of  the  VISAM  member 
DBSTEAT  of  the  7PAM  data  set  DSESLIB, 
This  action  is  accomplished  using  the 
routine  PSTBAT* 


b*  On-line  Terminal  Displays*  , 

The  following  is  displayed  if  a set  is 
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successfully  produced  from  the 
expression; 


(1) • a unique  set  numher  or  S-number, 

(2.)  The  number  of  citations  (or  keys) 

in  the  set 

(3.)  The  expression,  with; 

(a.)  E-numhers  replaced  with  the 
corresponding 
”fieldname=value”. 

(b.).  Values  which  return  a null  are 
notated  with  special  symbols, 
as;  aSE  =»*9999»«. 

(c.),  If  the  resultant  set  consists 
of  subfile  keys,  the 
expression  will  be  displayed 
with  the  subfile  name,  as; 

(FEOM; subfilename)  expression 

c.  Formatted  Print-outs 
Net  applicable 

d.  Punched  Card  Output  Files 
Not  Applicable 


4.  Beference  Tables 

а,  EXPTAB 
■b.  ELDTAB 
C.  flJCB 
d.  PAESED 

б.  SETAE 
f.  SaCHTAE 
g*  TC 

-h.  USEBTAB 


PEOCEESING  BEODIBEHENTS 
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1*  Top  level  Elowchart 
See  Pigure  2 
2.  NASEATI-VE 

The  SELECT  command  outputs  the  expression  and 
the  number  of  citations  (record  beys) 
associated  with  that  expression.  A unique 
set-number  or  S-number  is  assigned. , 

The  input  expression  is  a boolean  expression 
made  up  of  set-numbers,  S-numbers,  values. 
E-numbers  or  range  forms  of  these  terms. 

The  SELECT  command  is  processed  in  three 
phases; 

1.  Parsing 

2.  Expression  analysis 

3.  Execution  of  SELECT  "instructions” 

SELECT  parses  the  expression  in  three  passes. 
The  first  pass  recognizes  and  marks  as  such, 
letter  strings,  digit  strings,  operators, 
special  characters  and  delimiters.  Quoted 
• strings  are  recopied  to  remove  any  double 
guotes. 

The  second  pass  recognises  primary  elements 
such  as  S-numbers,  E-numbers,  set-numbers, 
values,  and  field  names.  Field  names  are 
marked  as  indexed  or  non-indexed. 

The  third  pass  recognises  groupings  of 
elements  such  as  range  forms  and  associates 
each  -value  in  the  expression  with  the  proper 
field'  name.  If  necessary  a prompt  with  ' the 
keyword  ’’FIELD"  is  done  to  obtain  the  field 
name.  This  pass  also  sets  up  SELECT  execute 
phase  instructions  for  the  creation  of  sets 
from  basic  terras  such  as  a set-number. 

Also,  during  the  third  pass,  a non-indexed 
field  name  appears  in  the  expression,  the 
proper  entries  are  made  in  SECHTAB  to  provide 
for  the  search  to  be  executed  later. . 

All  information  found  during  the  first  three 
passes  is  entered  into  PAFS_TAB  and 

PTAB_IEF0,  The  original  expression,  recopied 
quoted  strings,  and  other  necessary  character 
strings  are  all  contained  in  EAS.  Each 
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element  in  PJES^TAB  contains  an  index  <IDX) 
into  was  to  note  the  position  of  the  item 
described. 

The  next  phase  of  SELECT  analyses  the 
expression  algebraically  and  builds  execute 
phase  instructions  to  perform  the  proper 
operations.  If  a search  is  required 
instructions  are  built  to  post  final  entries 
in  SECHTAB,  before  the  search,  and  to 
retrieve  information  from  SBCHTAB,  after  the 
search,  for  final  evaluation  of  the 
expression, 

luring  expression  analysis,  the  ANDing  of  a 
‘search  term  with  another  set  is  noted,  and 
instructions  are  created  to  cause  the  search 
to  occur  only  within  the  set  ANDed  with  the 
search  term. 

After  the  second  phase  all  is  ready  for  final 
evaluation  of  the  expression  by  execution  of 
the  previously  created  instructions.  At  this 
time  the  input  command,  with  parameters,  is 
reconstructed  and  posted  in  the 
COEEENT_STEATEGI  data  set. 

If  a search  is  required,  all  SELECT  tables 
and  instructions  are  stored  for  use  at  the 
time  of  search  execution.  An  S-number  is 
assigned  and  this  number,  with  the 
expression,  is  output  to  the  terminal. 

If  no  search  is  required,  the  execution 
phases  of  SELECT  is  invoked.  The 
instructions  built  earlier  are  now  executed. 
Sets  are  created,  combined,  and  a altered  as 
the  expression  dictated,  until  the  final 
resulfant  set  is  obtained.  This  set  is 
assigned  a unique  number  and  posted  into 
SETAB  through  the  use  of  the  DBPSET  routine 
which  also  sends  a line  describing  the  set 
(set-  number,  size,  expression)  to  the 
terminal, 

Ehen  the  user  enters  the  EXECUTE  command  to 
invoke  the  search,  the  DBEXSB  program  is 
given  control.  This  routine  contains  all  of 
the  actual  search  logic,  however  repetitive 
calls  to  SELECT  (DBSLCT2  entry  point)  - are 
made.  The  execute  phase  instructions  are 
used  by  SELECT  to  control  the  search. 
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iTiring  a search  each  previously  defined 
S-number  has  associated  with  • it  an 
instruction  list.  The  first  instruction  in 
the  list  for  each  S-number  is  a ^branch" 
initialized  to  point  to  the  second 
instruction  in  the  list,  flhen  SELECT  is 
first  given  control,  each  instruction  list  is 
executed  until  an  S-number  or  a search  term 
instruction  is  encountered.  The  search 
instruction  posts  proper  final  information  to 
SFCHTAB  and  in  both  cases  execution  of  the 
instruction  list  is  suspended.  . A new  branch 
point  indicating  where  to  resume  execution  is 
stored  in  the  ’’branch”  instruction  at  the  top 
of  the  list. 

When  all  instruction  lists  have  been  executed 
as  far  as  possible,  control  is  returned  to 
LBEXSE  for  the  actual  search  to  take  place. 
After  this  SELECT  is  called  .again  and 
instruction  execution  is  restarted.  Some 
S-numbers  and  searches  may  now  be  evaluated. 
Again  each  instruction  list  is  executed  until 
an  undefined  S-number  or  search  term  is 
encountered  or  an  actual  set  is  created  and 
posted.  Again  control  returns  to  DBEXSB. 
This  process  continues  until  all  'instruction 
lists  terminate  by  posting  a set. 

The  SIABCH  is  iraplemented  simply  as  an 
additional  entry  (DBSLCT1)  into  SELECT.  The 
command  format  is  the  same  as  that  for  the 
SELECT  command,  thus  a valid  SELECT 
expressicn  may  be  used, 

BBSLCT1  is  the  entry  point  for  the  SEABCH, 
This  command  first  gets  and  verifies  the  set 
number  or  S-number  on  which  a linear  search 
is  to  be  performed,  SEABCH  then  prompts  the 
user  for  the  rest  of  the  search  expression  to 
be  performed  to  the  specified  set.  Once  the 
search  expression  is  entered,  then  SEABCH 
passes  this  information  to  the  search  option 
part  >of  the  SELECT  command.  When  control  is 
returned  to  SEARCH,  it  then  prompts  the  user 
for  another  search  to  be  performed,  on  the 
same  set  as  before.  This  loop  continues 
until  the  user  enters  a null  response  to  the 
search  expression  prompt,  at  which  time 
control  is  passed  to  the  calling  routine. 


CODIHG  SPECIEICATIOHS 
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1,  ■ Source  Language 

The  SELECT  command  module  is  written  in  the 
lBH/360  TSS  PL/I  programming  language.  The 
DBPL/I  language  extension  is  used  to  handle- 
all  access  to  the  files  in  the  data  base  and 
the  TSfL/I  language  extension  is  - used  to 
handle  all  communication  with  the  terminal. 

2.  Suggestions  and  Technigues 
Sot  Applicable 
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SELECT,  THE  SEiSCH  CPTIOH 


A.  MODULE  NAME 

letrieval,  SELECT  Search  Option 
Program  - ID  - EDBSLCT. 

Hoanle  - ID  - DBSLCT 

B.  . AHALISI 

0.  Kirt  Hearne 
Neoterics,  Inc, 

C.  Moaule  Eunction 

The  SELECT  search  option  is  a feature  of  the 
SELECT  commana  «hich  gui3es  the  user  through  a 
search  strategy.  The  SEARCH  coromand  is  ■ used  to 
define  a set  or  pseudo-set  to  he  used  as  the 
search  un’iverse. 

The  user  is  then  prompted  for  linear  search 
expressions  with  the  phrase; 

SELECT  {Set-numher  S-number)  IE; 

The  reply  is  of  the  same  format  as  the  SELECT 
command  itself; 

expression , field ,replace, method 

where  the  parameters  have  the  same  meaning  as  with 
the  SELECT  ccmmand. 

The  set^numher  or  S-number  defined  by  the  SEARCH 
command  is  added  along  with  an  AMD  boolean 
operator  to  the  left  end  of  the  expression  entered 
in  response  to  the  SELECT  IE  prompt.  The 
resultant  expression  is  then  sent  directly  to  the 
SELECT  command  processor. 

1,  Reference  Tables 

a.  EXPTAB 

b.  ELDTAB 
C.  HECB 

d. 


PARSED 
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e.  SETAB 

f.  SHCHTAB 

g.  1C 

h.  B SIB TAB 
BATA  BEQUIBEHENTS 

-1»  I/O  BlocS  Diagrain 
See  Pigure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Hot  Applicable 

b.  Punched  Card  Input  files 
Hot  Applicable 

c.  Input  Files 
Hot  Applicable 

d.  On-line  Terminal  Entries 

If  a terminal  is  the  source  of  search 
parameters  as  previously  defined,  the 
TSS  parameters  as  previously  defined, 
the  TSS  system  will  apply  default 
values,  if  available,  to  the  parameters 
when  no  values  are  entered, 

3.  Output  Bata  Sets 
a.  Output  Piles 

Using  the  PSTBAT  routine,  the  command 
string,  as  it  is  entered  and  validated, 
will  be  saved  in  the  region 
CDBBEHT^STBATEGY, 

PfiOCESSIHG  BEQUIBEHIHTS 

1,  Top  level  Flowchart 

See  Figure  2 


2 


Narrative 
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The  SELECT  Search  coromana  format  is: 

SES ECH  e xpression , field , replace , met hod 


which  results  in  a set-numher  or  s-numher* 
The  user  is  then  prompted  for  a linear 
search: 

SELECT  (Set-number  S-Euraber)  IF; 
expression 

field, replace, method 

The  set-number  or  S-number  is  added,  along 
with  an  AND  operator  to  the  expression  and 
the  result  is  sent  to  the  SELECT  command 
processor.  Thereafter  all  processing  is  the 
same  as  for  any  SELECT  expression. 

After  the  expression  is  processed,  the  user 
is  again  prompted  with  fhe  SELECT  IF 
prompt.  This  continues  until  a null  ■ is 
entered. 

COBIE6  SPECIFICATIOES 

1,  Source  Language 

The  SELECT  Search  command  is  written  in  the 
IBH/360  TSS  PL/I  programming  language.  The 
EBPL/I  language  extension  is  used  to  handle 
all  access  to  the  files  in  the  data  base, 
and  the  TSPL/I  language  extension  is  used  to 
handle  all  communications  . with  the 
terminal. 

2,  Suggestions  and  Technigues 
Hot  Applicable 


SAVE 

SET-NUMBER 


RETURN 


Figure  2.  Top  Level  Flowchart  - SELECl 
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TOPIC  E.5  BETEIEVAL  DISPLAI  CCHfflJND 


A.  HODULE  NAME 

Betrieval,  DISPLAY  command 
Program-ID  - EDBDSPI. 

Hodule«ID  ~ DBDSPL 

Primary  Entry  Point  (DBDSPL) 

Secondary  Entry  Point  (DBDSPLP) 

B.  AHALTSTS 

John  A«  Lozan 
Neoter ics , In  c« 

C.  MODULE  FUNCTION 

The  DISPLAI  command  is  a rontine,  called  by  the  TSS  , 
system r whose  pnrpose  is  to  allow  the  retrieval  system 
nser  to  have  designated  data  for  a given  set  to  be  ^ 
displayed  on  a terminal.  Like  the  PEINT  command,  the  ’ 
user  may  specify  the  format  of  the  output  as  the' 
citation  number,  the  citation,  the  abstract,  or  the 
full  text  for  any  item  contained  in  a set  which-  has 
been  previously  selected.  Optionally,  the  user  may 
prespecify  a format  of  his  own,  using  the  FOEHAT, 
command,  to  govern  the  DISPLAY  command.  One  set-number’ 
is  reserved  for  special  purposes  in  the  system. ■ 

Set-number  0 is  a logical  reference  to  the  entire 
anchor  file.  The  PAGE  command  also  calls  the  DISPLAY  • 
command  in  order  to  create  additional  displays,', 
logically,  before  and  beyond  the  current  one.  The  . 

calling  seguence  is:  DISPLAY  set-number,  format,  item,, 

type  or,  alternately,  DISPLAY  citation#,  format, 

D.  DATA  REQUIEEMENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c. -  Input  Files 
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The  anchor  and  associated  files  of  a data 
base  will  be  input  to  the  DISPLAY  command. 

d.  Oti'-line  Terminal  Entries 

The  parameters  available  to  the  DISPLAY 
command  are  set  or  citation  number,  format, 
items,  and  type.  The  EASIS  system  will  apply 
default  values  to  the  parameters,  if  they 
are  available,  when  no  original  values  are 
entered, 

3,  Output  Data  Sets 
a*  Output  files 

Not  Applicable 

b.  On-line  Terminal  Displays 

The  DISPLAY  command  will  output  a 
partially-formatted  display  of  the  items  in  a 
set  or  for  a specific  citation  number.  The 
content  of  the  display  depends  upon  the 
format  code  entered  as  the  second 
parameter, 

c.  formatted  Print-outs 
Hot  Applicable 

d.  Punched  Card  Output  Piles 
Net  Applicable 

4,  Reference  Tables 

a.  COLPOSM 

The  DISPLAY  command  refers  to  a COLPOHN  table 
when  a columnar  format  is  referenced, 

b.  USEBTAB 

This  table  contains  user-oriented  and  status 
information, 

c.  PLDTAB 

The  DISPLAY  command  refers  to  PLDTAB  to 
locate  the  appropiate  sequential  (SEQFORM)  of 
columnar  (COLPOBM)  format  table  and  for  a 
table  of  data  base  field  names  ordered 
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according  to  format  numbers  1-4. 

d.  EETDITA 

This  table  contains  data  fields  unigue  to  tbe 
retrieval  sub-system, 

e.  PlEX 

The  DISPLAY  command  uses  a DBPL/I  file  called 
PI-EX  for  all  of  its  retrievals  from  the  data 
base. 

f.  SEQPOEJ3 

The  DISPLAY  command  refers  to  a SEQEOEH  table 
when  a sequential  format  is  referenced, 

PEOCESSISG  EEQDIREKEHTS 

1.  Top  Level  Flowchart 
See  Figure  2 

2,  Narrative 

a.  Display 

The  DISPLAY  command  is  called  by  the  UASIS* 
system  by  the  director, 

b.  Accept  Parameters 

Since  the  parameters  are  not  passed  to  the 
DISPLAY  command,  by  the  director,  they  are 
retrieved  via  Terminal  Support  (TS) . The 
first  parameter  is  either  a ”set-numher”,  or 
a "citation  #",  The  second  parameter  is 
"format"  code,  the  third  is  an  "item"  number 
and  the  fourth  is  the  "type"  code.  The  last 
three  parameters  are  optional.  The 
"set-number"  is  a one  or  two  digit  number  and 
is  not  likely  a default  value  since  it  will 
change  for  every  command.  The  "citation  #" 
is  a character  string,  which  is  not  likely  to 
have  a default.  If  no  entry  is  made  and  no 
default  exists,  then  an  error  is  reported  and 
control  passed  back  to  the  calling  routine. 
The  "format"  code  is  a value  of  1 to  25 

designating  a seguential  format  or  FI  to  F25 

designating  a columnar  format,  or  a format 

name  representing  one  of  the  above  format 
values  or  a fieldname.  If  no  entry  or 
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default  is  present,  the  value  ”2”  is  provided 
for  anchor  key  sets  or  ”5”  for  subfile  sets. 
The  ”itei8”  parameter  designates  the  member  of 
the  specified  set.  The  entry  is  a character 
string  having  a numeric  value.  If  no  entry 
or  default  is  given  for  this  parameter,’ the 
first  item  in  the  set  is  displayed.  The 
"type”  code  indicates  whether  the  user  wants 
subfile  information  to  be  displayed 
continually  following  the  anchor  data,  and  if 
so,  whether  the  data  fields  of  each  subfile 
record  are  to  be  exhausted  seguentially  or 
the  data  field  values  are  to  he  exhausted 
across  subfiles  before  proceeding  to  the  next 
field.  An  invalid  entry  is  reported  before 
returning  control  to  the  calling  routine.  If 
all  parameters  have  valid  values,  then 
execution  continues  with  the  next  section. 

The  DISPLAY  command  is  placed  as  the  next 
record  in  the  strategy  data  set  by  a call  to 
the  save  strategy  routine.  The  parameters  to 
this  subroutine  are  the  word  DISPLAY  and  its 
parameters  in  their  normal  order, 

c.  First  Page  Initialization 

Depending  on  the  "class”  of  the  first 
parameter,  certain  specific  initialization  is 
necessary.  If  the  parameter  is  a data  base 
key  (class  1),  e.g, , a citation  number,  then^ 
the  anchor  record  is  read  and  a heading 
prepared.  If  the  parameter  is  a set  number 
(class  2) , the  relative  key  is  taken  from  the 
set  and  used  to  read  the  anchor  record  and-  a 
heading  prepared.  Control  is  transferred  to 
Section  (f)  below, 

d.  Page  DISPLAY 

The  DISPLAY  command  is  entered  at  this 
secondary  entry  point  from  the  PAGE  command. 
The  paging  direction  and  mode  are  indicated 
by  the  PAGE  parameters, 

e.  Validate  Next  Page 

If  the  page  requested  has  been  seen  before, 
it  need  not  be  regenerated,  but  may  be 
retrieved  from  based  storage,  where  it  was 
saved,  and  control  can  be  transferred  to 
Section  (q)  below  to  display  it.  When 
non-contiguous  skip  paging  is  being  done,  the 
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relative  key  is  taken  from  the  set  and  the 
anchor  record  read. 

Build  Screen  Image 

This  is  a common  routine  for  building  a 
EISPIAY  screen  image  either  for  an  original 
IISPLM  command  or  for  a PAGE  command* 

Por  a sequential  format,  field  names  are 
taken  successively  from  the  SEQFOBH  down  to 
the  number  of  field  names. 

In  the  most  general  case,  each  field  consists 
of  multiple  elements  and  each  element  value 
is  so  long  as  to  require  multiple  lines  of  a 
buffer.  The  first  line  for  the  .first  element 
of  a field  is  tagged  with  the  fieldname  and  a 
colon.  The  first  line  for  an  element  after 
the  first  of  a field  is  tagged  with  only  the 
colon.  Successive  lines  after  the  first  for 
an  element  have  their  tag  entirely 
suppressed.  The  degenerate  cases  of  a single 
element  field  and/or  an  element  short  enough 
to  fit  on  one  line  of  the  buffer  are  handled. 
And  if  the  field  is  null  (no  data  present) , 
nothing  is  posted  to  the  buffer  at  all  for 
that  field  name. 

Subfile  resident  fields  are  displayed  similar 
to  multiple'  elements;  however,  the  first 
element  of  the  field  per  subfile  record  has 
the  field  name  tag  duplicated,  and  a special 
heading  is  displayed  (depending  on  the  ”type" 
parameter)  as  each  new  subfile  record  is 
processed. 

If  the  field  names  are  not  all  processed 
before  the  bottom  line  of  the  buffer  is 
reached,  the  routine  is  left  in  such  a state 
that  it  will  resume  where  it  left  off  if 
normal  forward  paging  is  attempted.  But  if 
the  field  names  are  all  used,  then  the 
remaining  lines  are  cleared. 

Tor  a columnar  format,  the  optional  page 
number,  title,  and  header  lines  are  copied 
into  the  buffer.  Then  field  names  are  taken 
successively  from  the  COIFOEfl,  and  used  to 
retrieve  the  field  values  which  are  arranged 
across  a line  of  the  buffer.  If  there  are 
any  multiple  element  fields,  futher  lines  of 
the  PI-DTAB  buffer  are  used  for  remaining 
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elements  Tintil  the  record’s  desired  fields 
•have  all  been  retrieved.  If  there  are  any 
further  records  in  the  set,  the  next  record 
is  read  and  the  process  repeated,  Uhen  the 
buffer  is  full,  the  routine  is  left  in  such  a 
state  that  it  will  resume  where  it  left  off 
if  normal  or  skip  paging  is  attempted.  But 
if  the  data  is  exhausted,  then  the  remaining 
lines  are  cleared, 

g,  ^{rite  Screen 

Using  the  full  screen  mode  of  output,  the 
current  screen  image  is  displayed  on  the 
terminal, 

h,  Return 

Do  a normal  return  to  the  calling  routine, 

3,  Submodules  Bequired 

a,  DB  - data  base  package 

b,  PSTEAT  ^ save  strategy 

c,  IS  - terminal  support  package 
a,  , SETS  - set  information  package 

CODING  SPECIEICATIONS 

1,  Source  language 

The  DISPLAY  command  is  coded  entirely  with  the  IBH 
PI/I  programming  language.  The  DBPL/I  language 
extension  is  used  to  handle  all  access  to  the 
files  in  the  data  base.  The  TSPL/I  language 
extension  handles  all  instances  of  commnnication 
with  the  terminal. 

2.  Suggestions  and  Techniques 

Not  Applicable 
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TOPIC  P.6  - BETEIEVAl  PEINT  COEHAND 


A.  . HODULB  BA ME 

Betrievalr  peint  coinmana 
Prograia-ID  - EDBPHBT 
Bodule-ID  - DBPEHT 

Entry  Point  (DBPBHT) 

B.  ANAXYSTS  • 

Garth  B«  Byman 
Billiam  H.  Petrarca 
Neot erics r Inc. 

C.  MODDXE  PUHCTION 

The  PEINT  command  is  a routine  whose  purpose  is  to 
allow  the  retrieval  system  user  to  have  designated  data 
for  a given  set  listed  on  a high-speed  printer.  Like 
the  DISPLAY  command,  the  user  may  specify  the  format  of 
the  output  as  the  citation  numher,  the  citation,  the 
abstract,  or  the  full  text  for  any  item  or  range  of 
items  contained  in  a set  which  has  been  previously 
selected.  Optionally,  the  user  may  prespecify  a format 
of  his  own,  using  the  POEHAT  command,  to  govern  the 
PRINT  command.  All  of  the  uses  of  the  PRINT  cpmmand 
during  a single  terminal  session  will  be  accumulated 
and  printed  out  as  one  continuous  output  for  the  user 
to  pick  up  at  a later  time.  Three  set  numbers  are 
reserved  for  special  purposes  in  the  retrieval  system. 

. Set-nnmber  99  is  an  array  in  core  used  by  the  KEEP 
command  to  store  parameter  lists  for  the  DISPLAY  and 
PRINT  commands.  set-number  98  is  a data  set  used  by 
the  SAVE  command  to  store  screen  images  for  later 
processing  by  the  DISPLAY  and  PRINT  commands. 
Set-number  0 is  a logical  reference  to  the  entire 
anchor  file.  The  calling  sequence  is:  PRINT 

set-number,  format,  item  (s)  or,  alternately,  PRINT 
citation#,  format, 

D.  DATA  REQ.DIREHENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 
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b.  Punched  Card  Input  Tiles 
Sot  Applicable 

c.  Input  Files 

The  -anchor  and  associated  files  of  a data 
base  are  input  to  the  PBINT  command.  The 
SAVTILE  containing  display  screen  images 
stored  by  the  SAVE  command  is  also  input  to 
the  PHIHT  command. 

d.  On-line  Terminal  Entries 

The  parameters  available  to  the  PBINT  command 
are  "set-number”,  or  "citation  number”, 
"format”,  and  "items,”  NASIS  vill  apply 
default  values  to  the  parameters  if  they  are 
•available,  when  no  original  values  are 
entered, 

3,  Output  Bata  Sets 
a.  Output  files 

The  output  of  the  FEINT  command  consists  of  a 
data  set  containing  the  line  images  to  be 
sent  to  the  high-speed  printer  at  the 
conclusion  of  the  current  terminal  session. 
The  line  images  consist  of  op  to  132 
characters,  preceded  by  a carriage  control 
character, 

h.  On-line  Terminal  Displays 
Not  Applicable 

c,  Formatted  Print-outs 

When  the  current  strategy  is  terminated,  then 
the  actual  printing  process  is  initiated. 
The  description  of  this  output  is  contained 
in  the  Data  Set  Specifications  Section  of  the 
Development  workbook, 

d.  Punched  Card  Output  Files 
Not  Applicable 

4.  Deference  Tables 
a,  COIFOEM 
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The  PEIST  coramand  refers  to  a COIFOHH  table 
vfhen  a coltinaar  format  is  referenced. 

b.  FLDTAB 

The  P8IHT  command  refers  to  FOIIUTAB  to  locate 
the  appropiate  sequential  (SEQIOBfi)  or 
columnar  <COLFOBH)  format  table  and  for  a 
table  of  data  base  field  names  ordered 
according  to  format  numbers  1-4. 

c.  USESTAB 

This  table  contains  user-oriented  and  status 
information. 

d.  KEPTAB 

The  FEIHT  command  refers  to  KEPTAB  vhen  the 
special  set  99  is  used  for  a PEIET 

specification  that  was  previously  stored  by 
the  KEEP  command, 

e.  PlEX 

The  FEIKT  command  uses  a DBPL/I  file  called 
PlEX  for  all  of  its  retrievals  from  the  data 
base. 

f.  PEIHTES 

The  PRIMT  command  uses  a Pl/I  file  called 
PBINTEE  to  write  all  of  its  printer  line 
images  for  ultimate  off-line  printing. 

g.  PETDSED  in  BETBATA 

The  PEIHT  command  tests  this  switch  to 
determine  whether  to  write  line  images  fox  a 
lead  page  identifying  the  report  and  then 
sets  the  PBTBSED  switch  to  indicate  that 
there  are  line  images  for  off-line 
printing. 

h.  SECHTAB  . 

This  table  contains  S-number  information. 

X.  SA7FIIE 

The  PBIMT  command  uses  a Pl/I  file  called 
SAVFILE  for  all  of  its  retrievals  from  the 
special  set  98  of  screen  images  previously 
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s-fcored  by  the  SAVE  command. 

j.  SEQFOEM 

The  . PBIMT  command  refers  to  a SEQFOBH  table 
when  a segnential  format  is  referenced. 

k.  EETDAIA 

This  table  contains  data  fields  unique  to  the 
retrieval  system. 

l.  ADDBESS  in  EETDATA 

The  PBIHT  command  refers  to  ADDRESS  when 
writing  line  images  for  the  lead  page  of  the 
report. ^ 

m.  NAME  in  BETDATA 

The  PBIST  command  refers  to  UAHE  when  writing 
line  images  for  the  lead  page  of  the 
report, 

PBOCESSIRG  SEQDIEEKENTS 
1,  Top  Level  Flowchart 
See  Figure  2 
-2,  Narrative 

a.  Record 

The  PRINT  command  is  called  by  the 
director* 

b.  Accept  Parameters 

Since  the  parameters  are  passed  to  the  PRINT 
command  through  Terminal  Support,  they  are 
arranged  in  a keyword  or  predefined  order. 
The  first  parameter  is  either  a ’’set-number”, 
as  defined  by  a SELECT  or  LIHIT  command,  or  a 
’’citation  #”  or  an  ”S-number”  as  defined  by  a 
SELECT-IE  command.  The  second  parameter  is  a 
’’format”  code,  and  the  third  is  an  ’’item” 
number  or  range  of  numbers,  ' The  latter  two 
parameters  are  optional.  The  set  number  will 
be  a one-  or  two-digit  number  and  will  not 
likely  have  a default  value  since  it  changes 
for  every  command.  The  ’’citation  #”  is  a 
character  string  which  also  will  not  likely 
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have  a default.  If  no  entry  is  made  and  no 
default  exists,  then  the  error  is  reported 
and  control  passed  bach  to  the  calling 
routine.  The  ’'format”  code  only  applies  to  a 
PRINT  of  a "citation#”  or  of  set  0 ~ 9-7,  It 
is  a value  of  1 to  25  designating  a 
sequential  format  or  El  to  E25  designating  a 
columnar  format  or  a format  name  representing 
one  of  the  above  format  numbers.  If  no  entry 
or  default  is  present,  the  value  of  t«o  is 
provided  for  anchor  key  sets  or  four  for 
subfile  sets.  The  "item"  parameter  is  not 
required  when  the  "citation  #"  is  entered  as 
the  first  parameter;  otherwise,  it  designates 
the  member  or  range  of  members  of  the 
specified  set.  The  entry  is  a character 
string  cf  one  to  eleven  positions,  when  a 
range  of  items  is’  entered,  the  two  values 
are  separated  by  a hyphen.  If  no  entry  or 
default  is  given  for  this  parameter,  all  of 
the  items  in  the  set  are  printed.  An  invalid 
entry  will  be  reported  before  control  is 
returned  to  the  calling  routine.  If  all 
parameters  have  a valid  value,  then  execution 
continues  with  the  next  section. 

The  PBIHT  command  is  placed  as  the  next 
record  in  the  strategy  data  set  by  a call  to 
the  save  strategy  routine.  The  parameters  to 
this  subroutine  are  the  word  PRINT  and  its 
parameters  in  their  normal  order. 

If  the  first  parameter  was  an  S-nuraber, 
processing  continues  with  Section  (g)  . 
below. 

Initialisation 

The  data  set  for  the  printer  file  ■will  have 
been  defined  in  a procdef  before  the  PRINT 
command  is  called.  The  first  time  the  PRINT 
command  is  used,  it  writes  line  images  for  a 
leader  page  identifying  the  user’s  name  and 
mail  stop  for  distribution. 

If  the  first  parameter  specifies  the  special 
set  98  of  saved  screen  images,  processing 
continues  at  Section  (f)  below.  If  it 
specifies  a data  base  key,  e.g, , a citation 
number,  then  the  anchor  record  is  read  and 
processing  continues  at  Section  (D)  below. 
If  the  parameter  is  a set  number,  then  it  is 
examined  for  validation  and  the  first 
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relative  key  specified  by  the  item  range 
parameter  is  taken  from  the  set  and  used  to 
read  the  first  anchor  record.  If  the 
parameter  refers  to  the  special  set  99  of 
kept  items,  then  KEPIAB  is  examined  to  find 
the  first  relative  item  specified  by  the  item 
range  parameter  and  the  first  relative  key 
specified  by  the  item  range  in  KEPTAB  is 
taken  from  the  set  and  used  to  read  the  first 
anchor  record, 

d.  Process  from  Data  Base 

Eor  a seguential  format,  field  names  are 
taken  successively  from  the  SEQFOEH  beginning 
nith  the  key  field  name  down  to  the  number  of 
field  names, 

Xn  the  most  general  case,  each  field  consists 
of  multiple  elements  and  each  element  value 
is  so  long  as  to  require  multiple  lines  on 
the  printer  file. . The  first  line  for  ‘ the 
first  element  of  a field  is  tagged  with  the 
fieldname  and  a colon.  The  first  line  for  an 
element  after  the  first  of  a field  is  tagged 
with  only  the  colon.  The  first  subfile  field 
value  per  subfile  record  retains  the  field 
name  as  a tag;  however,  subsequent  elements 
axe  nevertheless  tagged  with  only  a colon. 
Successive  lines  after  the  first  for  an 
element  will  be  automatically  wrapped  around 
to  new  lines  by  the  PL/I  stream  output  and 
• are  tagged.  If  the  field  is  null  {no  data 

present) , nothing  is  written  at  all  for  that 
field  name.  The  PL/I  stream  output  will 
detect  the  logical  end  of  page  condition  so 
that  page  heading  lines  can  be  inserted  and 
then  normal  outputting  resumed, 

e.  He- initialization 

If  a data  base  key  is  specified  by  the  user, 
this  Section  is  bypassed  and  control  is' 
returned  at  Section  (g)  below. 

If  there  are  more  keys  in  the  set  within  the 
range  specified  hy  the  user  or  in  the  KEPTAB 
item,  then  the  new  key  is  taken  and  used  to 
read  another  anchor  record  and  control  loops 
back  to  Section  (d) . Hhen  this  loop  is 
completed,  control  is  returned  at  Section  {g) 
below  unless  the  user  had  specified  a range 
of  kept  items  from  set  99.  In  that  case,  the 
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next  Jcept  item  is  taken  from  KEPTAB  and  the 
first  ■ relative  key  specified  by  the  item 
range  in  KEPTAB  is  taken  from  the  set  and 
nsed  to  read  another  anchor  record  and 
control  loops  back  to  Section  <d) . Einally, 
control  is  returned  at  Section  (g)  below. 

For  a columnar  format,  the  optional  page 
number,  title,  and  header  lines  are  put  out 
at  the  top  of  each  page  of  output.  Field 
names  are  taken  successively  from  the  COLFOBH 
and  used  to  retrieve  the  field  values  which 
are  arranged  across  the  output  line.  If 
there  are  any  multiple  element  fields,  father 
lines  are  put  out  until  the  record's  desired 
fields  have  been  retrieved, 

f.  Process  from  SAVFIIE 

One  or  a contiguous  range  of  saved  screen 
images  are  successively  retrieved  from 
SAVFILE  (set  98) • For  each  screen  image,  a 
page  heading  line  is  written  followed  by  the 
screen  image  subdivided  into  lines  the  same 
length  as  the  display  screen  width  so  that 
the  appearance  is  identical, 

g,  Eeturn 

When  all  processing  for  the  PEINT  command  has 
been  completed,  control  is  returned  to  the 
calling  routine. 

3.  Subroutines  Bequired 

a,  DB  - data  base  package 

b,  PSTEAT  save  strategy 

c,  TS  - terminal  support  package 

d,  SETS  - set  information  package 
F.  CODING  SPECIFICATIGNS 

1,  Source  Language 

The  FEINT  command  is  coded  entirely  with  the  IBH, 
Pl/I  programming  language.  The  DBPI/I  language 
extension  is  used  to  handle  all  access  to  the 
files  in  the  data  base,  and  the  TSPl/I  extension 
handles  all  instances  of  communication  with  the 
terminal. 
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Suggestions  and  Technigues 

a.  normal  PL/I  statements  are  used  to  write  the 
.line  images  to  the  print  data  set-, 

b,  Ihe  many  external  variables  required  in  the 
PBINT  command  are  combined  into  external 
data  structures,  in  many  cases*  This 
requires  only  one  name  to  be  an  external 
symbol. 
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TOPIC  E..7  » BETEIEVai  EXECOTE  COMHANE 


a, . HODOIE  NAME 

Retrieval,  EXECUTE  CoiBniaiiS 
Program-IE  - EDBEXSB 
MoSule-lD  - DBEXSB 

B.  ANALTSTS 

Barry  G,  Hazle-tt 
William  H,  P-etrarca 
Heoterics,  Inc. 

C.  MODULE  FUNCTION 

Use  of  the  EXECUTE  command  informs  the  NASIS  system 
that  user  has  specified  all  of  his  SEIECT-IF  and/or 
PBINT  commands  for  his  linear  search  and  is  now  ready 
to  have  them  executed. 

The  format  of  the  Execute-Search  command  is  as 
follows: 

EXECUTE 

Use  of  the  EXECOTE  command  informs  the  NASIS  system 
that  the  user  has  specified  all  of  his  search  requests 
on  a set  and  is  now  ready  to  have  them-executed.  When 
an  attention  interrupt  is  made,  the  EXECUTE  command 
will  return  the  user  with  its  current  status;  i.e. , the 
number  of  processed  records  and  the  number  of  records 
to  be  processed.  To  continue  any  further  in  the 
execution  of  the  linear  search,  the  user  oust  then 
enter: 

GO  which  will  • resume  the  search  at  the 

point  of  execution,  or 

END  which  will  cancel  the  search  in 

progress,  returning  the  user  to  the 
point  of  his  strategy  immediately  before 
the  last  EXECUTE. 

D.  DATA  BEQUIEEHENTS 

1,  I/O  Block  Diagram 
See  Figure  1 


2. 


Input  Data  Sets 
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a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  files 

The  data  base  anchor  file  is  accessed  to 
obtain  the  records  for  the  linear  search, 

d.  On-line  terminal  Entries 

If  a Terminal  is  the  source  of  EXECUTE 
parameters, 

3,  Output  Data  Sets 

a.  Output  Files 

Using  the  PSTEAT  routine,  the  command  string, 
as  it  is  entered  (modified  if  any  by  prompt 
responses)  and  validated,  is  saved  in  the 
region  CUREENT-STEATEGY  of  the  VISAM  member 
DBSTSAT  Of  the  VFAH  data  set  USEELIB.  For  a 
complete  description  of  the  data  set  DBSTEAT, 
refer  to  the  Specifications  for  the  module 
EBGPS  (DEB,  Section  IV,  Topic  F,8). 

b.  On-Line  Terminal  Displays 

The  following  is  displayed  at  the  output 
interface: 

1,  new  set  number, 

2,  items  contained  in  a new  set,  and 

3,  the  (combined)  expression  describing  the 
new  set, 

for  each  set  created  as  the  result  of  the 
linear  search, 

c.  Formatted  Print-outs 
Hot  Applicable 

d.  Punched  Card  Output  Files 
Not  Applicable 


4 


Reference  Tables 
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a.  PLDTaB  is  the  descriptor  field  table 

referenced  to  determine  whether  a search 
field  name  is  an  inverted  index*  The  anchor 
file  key  field  name  is  used  from  ELETaB, 

b*  SECHTIB  is  the  search  table  referenced  to 

maintain  search  testing  criteria,  pseudo-set 
information,  and  search  list  pointers. 

PROCESSING  SEQDIREaENTS 

1,  Top  Level  Elowchart 
See  Figure  2 

2,  Narrative 

I 

The  EXECUTE  calling  sequence  is  as  followst 
can  EBEXSR 

Search  processing  will  follow,  the  following 
steps; 

1.  Notify  STaTISTICS  of  the  search  and  what 
data  base. 

2.  Identify  a search  set;  group  tests  on 
that  set. 

3.  Bead  in  records  of  the  the  search  set 
one  at  a time. 

4.  For  each,  record  test  each  field  against 
its  corresponding  test  criterion  as 
defined  in  the  IS  strategy. 

5.  Each  successful  record  is  added  to  a 
search  list  associated  with  the 
pertinent  test  pseudo- set. 

6.  after  all  records  have  been  tested,  new 

sets  are  made  with  the  lists  for 

pseudo-sets  defined  by  the  SEIECT-IF 
command. 

7.  Each  pseudo-set  defined  by  a Booolean 
SELECT  is  made  into  a set  via  a call  to 
a special  entry  point  in  the  SELECT 
command. 

8.  If  there  is  another  set  to  search 

continue  at  step  2. 
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m 

S.  All  pseuao-sets  requiring  a "PBINT”  are 
printed  Tria  a call  to  tlie  PfilKT  conmand 
(DEPBUTS)  . 

At  the  search  termination  all  unnecessary  dynamic 
storage  will  be  freed.  In  addition  a special 
entry  point  into  the  EXECUTE  module  for  the.  CAHCEI 
command  will  accomplish  the  same  function. 

CODING  SPECIEICATIOUS 

1.  Source  language 

The  EXECUTE  command  is  written  in  the  IBM/360  TSS 
Pl/I  programming  'language.  The  DEPl/I  and  TSPl/I 
language  extensions  are  used  for  data  base  file 
accessing  and  terminal  communication, 

respectively, 

2,  Suggestions  and  Techniques 

It  is  suggested  that  considerable  analysis  be  made 
of  search  universes  to  determine  the  final  search 
universe  for  the  EXECUTE  command  due  to  the  rather 
large  data  bases  that  may  exist.  The  success  of 
reducing  a search  universe  to  its  minimal  size  is 
reflected  to  the  user  in  response  time. 


GROUP  S#’S 
ON  SEARCH 
SET  FOUND  ’ 


Figure  2.  Top  level  flowchart 
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TOPIC  F. 8 PETEIE7AL  SIfS  COEHAKD 


■A,  aODULE  UAME 

SETS  Command  and  Sets  fianagement 
Program-ID  - PDBSETS 
Module-ID  - DBSETS 

Entry  Points  - (DBSETS,  DBGSET,  DBPSET,  DBPAGST) 

B«  AWALYST 

James  A.  Wesley 
Keoterics,  Inc. 

C,  SODDIE  FUNCTION 

The  primary  tunction  of  the  DBSETS  module  is  to  display 
to  the  NASIS  Eetrieval  Sub-system  user  a list  of  the 
sets  or  s-numbers  he  has  formed  during  the  current 
strategy  session.  The  list  is  displayed  in  the  form? 
set  number  or  s-number  (including  the  subfile  suffix, 
if  present),-  the  number  of  items  in  the  set,  and  the 
expression  that  formed  the  set. 

The  entry  points  DBGSET  and  DBPSET  are  called  from 
application  programs  to  GET  SETS  and  POST  SETS, 

respectively. 

The  entry  point  DBPAGST  is  called  by  the—  PAGE  command 
to  display  the  next  *page»  of  sets  in  the  user’s 
current  strategy, 

■D*  DATA  BEQUIBEHENTS 

*1«  I/O  Block  Diagram 

See  Figure  1 

•2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

SETAB  and  STEATEGY.LIBBARY 
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4*  On-line  Terminal  Entries 
Kct  Applicable 

3,  Output  Eata  Sets 
a«  Output  Files 

SETAB  and  STHATEGI.LIBBABY 

b.  On-line  Terminal  Displays 

The  terminal  display  from  this  module  «ill 
consist  of  a list  of  the  set  numbers  or 
s-numbers  (including  the  subfile  suffix,  if 
applicable) , the  number  of  items  in  the  set 
and  the  expression  that  formed  the  set. , 

c.  Formatted  Print-Outs 
Eot  Applicable 

d.  Punched  Card  Output  Files 
Not  Applicable 

4,  Reference  Tables 
a,  SETAB 

■ b.  TS 

c.  DB 

d.  STRATEGY. LIERABi 

e.  SBCHTAB 
PROCESSING  EEQUIEEKENTS 

1.  Top  Level  Flowchart 
See  Figure  2 

2,  Narrative 
a.  DBSETS 

Upon  entry  at  the  DBSETS  entry  point,  it 
allocates  and  initializes  a controlled  area 
for  the  current  user  to  keep  track  of  his 
paging  operations. 
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Ihe  module  looJcs  for  any  parameters  that  were 
passed  uitli  the  command.  If  there  are  none, 
the  module  will  default  to  set  numbers  and 
start  displaying  at  the  beginning  of  SETAB, 

If  a number  between  1 and  97  is  passed,  the 
module  verifies  that  as  a 7alid  set  number 
and  starts  the  displaying  with  that  number. 

If  the  parameter  is  an  *S*  the  module  will 
display  s-numbers  (pseudo-sets) , A second 
parameter  may  be  included  here  to  indicate 
starting  at  a specific  s- number. 

This  processing  continues  until  the  bottom  of 
SETAE  or  SBCHTAE  is  encountered  or  the  TS 
supervisor  indicates  the  output  screen  is 
full  and  automatically  writes  the  screen. 

BESETS  saves  the  set  number  or  s-number,  that 
would  have  caused  the  screen  overflow,  in  the 
user  control  table.  This  set  number  or 
s-number  is  then  used  as  the  first  number  to 
appear  on  the  next  page  forward. 

•b,  IBPAGST 

This  entry  point  is  called  by  the  TS 
supervisor  when  the  user  wishes  to  page  in 
either  a forward  or  backward  direction 
through  his  list  of  sets. 

Upon  entry  DBPAGST  vaidates  the  command  and 
(re) constructs  a page  in  the  appropriate 
direction.  Only  the  letter  *B*  will  cause  a 
backwards  page  operation;  anything  else 
defaults  to  forward, 

c.  IBPSET 

This  entry  point  is  available  to  the 
application  programmer  who  wishes  to  post  a 
new  set  and  its  corresponding  data  to  SETAB, 
The  calling  sequence  follows; 

CALL  DBPSET  (POIHTIB, EXPRESSION, SET#)  ; 

Nhere; 

POINTEE  - is  a pointer  variable  passed  by  the 
user.  It  points  to  the  list  ±o  be  posted, 

EXPRESSION  - is  a varying  length  character 
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string,  maximum  256  bytes.  It  is  passed  by 
the  user  as  the  expression  that  formed  the 
set  to  be  posted. 

SEI#  - is  a varying  character  string,  maximum 
2 bytes  long.  It  is  passed  by  the  user  as 
the  one  byte  subfile  suffix  character  for  the 
set  being  posted  and  is  returned  by  DBPSET  as 
the  2 byte  set  number  on  a successful  posting 
cr  a null  string  to  indicate  an  1/0  error  or 
no  more  sets  available. 

This  entry  point  first  checks  for  a slot  in 
SETAB;  if  none  are  available,  it  sets  the  set 
number  variable  to  null  and  returns  to  the 
user. 

If  a set  number  is  available, it  verifies  the 
suffix  as  being  between  Q and  2 or  it  assigns 
a blank  suffix.  . DBPSET  then  collects  and 
posts  the  data  to  SETAB  and  the  STRATEGY 
LIBRARY.  It  posts  the  set  number  for  the 
user  and  returns.  . 

d.  > DBGSET 

This  entry  point  is  available  to  the 
application  programmer  who  wishes  to  get  and 
verify  a given  set  number.  The  calling 
sequence  follows; 

CALL  DBGSET (SET#, POINTER, #LIST,SDPEIX) ? 

Rhere; 

SET#  - is  a varying  length  character  string, 
maximum  3, bytes  long.  The  user  passes  this 
variable  as  the  set  number,  and  optionally 
the  subfile  suffix,  to  be  gotten  and 
verified.  If  either  the  set  number  or  the 
suffix  is  invalid,  that  is,  a non-existent 
set  number  or  a wrong  suffix,  this  variable 
is  returned  as  null, 

POINTER  - is  a pointer  variable.  It  is 
returned  by  DBGSET  as  a pointer  to  the  set 
(list) • 

#LIST  - is  a integer  full  word.  It  is 
returned  by  DBGSET  as  the  number  of  2REES  in 
the  set, 

SDFPIX  - is  a single  character.  It  is  always 
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returned  as  the  correct  suffix  for  the  set 
requested.  In  the  event  an  invalid  suffix  is 
specified  in  the  set  number,  the  set  number 
is  returned  as  null  and  the  correct  suffix  is 
returned  here. 

EBGSET  first  separates  the  set  number  from 
the  suffix  and  verifies  both.  If  either  is 
invalid,  set  number  is  returned  as  null  and 
the  correct  suffix,  if  available,  is  put  in 
sun’ll.  If  the  validation  is  successful,  the 
set  number,  the  list  pointer,  the  number  of 
XEEES  and  the  suffix  are  returned  to  the 
caller. 

CODIHG  SPECIFICATIONS 
1.  Source  language 

The  EDESETS  command  module  is  written  in  the 
IBM/360  TSS  Pl/I  programming  language.  The  DBPX/I 
and  TSPI/I  language  extensions  are  used  for  data 
base  access  and  terminal  I/O,  respectively. 

Suggestions  and  Techniques 

Not  Applicable 
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Figure  2A.  Top  Level  Flowchart 
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Figure  2B . Top  Level  Flowchart 
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TOPIC  -F,9  - GENIBIC  KEY  XISTS 

a.  MODULE  NAME 

Program-ID  - RDBGEKB 
Module-ID  - DBGEHB 

■B.  AKALYST 

Johu  A.  Lozac 
Neoterics,  Inc. 

C.  MODULE  FUNCTION 

This  module  expands  or  contracts  lists  of  generic  keys 
based  upon  the  user’s  specifications  and  the  generic 
key  description  table. 

D.  DATA  BEQUIEEHENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Mot  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  anchor  and  index  files  of  a data  base  may 
be  used  for  input  by  the  program* 

d.  On-Line  Terminal  Entries 

The  program  prompts  the  user  for  the  FIELD 
(sub-level  name)  and  SET  parameters. 

3.  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-Line  Terminal  Displays 
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The  program  isrites  diagnostic  messages  to  the 
nser  for  any  errors  encountered. 

c,  Eormatted  Print  Outs 
Not  Applicable 

d.  Punched  Card  Output  Files 
Hot  Applicable 

4.  Eeference  Tables 

The  program  uses  the  following  tables  to  obtain 

information  necessary  to  perform  its  function, 

FIDTAB 

GEHEIIC 

PBOCESSING  BFQTJIBIHXHTS 

1,  Top  Level  Flowchart 

See  Figure  2 

2.  Narrative 

a.  1BGEHB1 

At  this  entry  point  the  program  initializes 
itself  to  process  data  passed  by  another 
program,  A switch  is  set  to  indicate  this 
fact,  so  that  parameter  prompting  and  the 
posting  of  SETAB  can  be  bypassed, 

b.  DBGEHE 

At  this  entry  point  the  program  initializes 
itself  to  process  the  user’s  GENERATE 
command.  It  extracts  the  current  file-  name 
from  FLDTAB  and  calls  the  generic  key  routine 
to  obtain  the  generic  key  description  table* 
The  program  then  prompts  for  and  verifies  the 
two  parameters.  If  the  SET  parameter  is  not 
a valid  set  number,  the  program  uses  it  as  a 
key  and  reads  the  anchor  file  to  verify  it. 
If  any  errors  are  detected  during  the  above 
operations,  the  program  terminates  with  an 
appropriate  diagnostic  message. 

The  list  described  by  the  second  parameter  is 
analysed  to  determine  the  generic  sub-level 
represented  by  its  keys.  This  result  is 
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compared  against  the  sub-level  defined  by  the 
first  parameter  to  determine  whether  this  is 
a request  for  parent  or  children 
processing. 

lor  parent  processing,  the  list  of  Keys  is 
analyzed,  one  at  a time,  and  the  unique 
parent  or  root  records  are  derived  and  posted 
to  a resultant  list.  This  processing  is  done 
by  the  structural  analysis  of  the  Keys,  based 
upon  the  sub-levels  determined  above. 

Eor  children  processing,  the  generic  key 
index  field  name  is,  extracted  from  the 
generic  key  description  table.  The  input 
list  of  keys  is  used  to  read  this  index  file 
by  key.  As  each  record  is  read,  the  list  of 
cross  references  is  »*or»ed»»  logically  to 
the  previous  list  of  cross  references 
creating  an  aggregate  list,  ^ben  the  end  of 
the  input  list  is  reached,  the  sub-levels  are 
compared,  and  if  more  sub-levels  remain  to  be 
processed,  the  resultant  cross  reference  list 
is  used  as  the  new  input  list  and  the  process 
is  repeated, 

at  fhe  completion  of  list  processing,  for 
either  parent  or  children  lists,  the  program 
posts  the  resultant  list.  If  entry  was  to 
DBGENE,  this'  involves  a call  to  DBPSET  to 
port  SETAB,  If  entry  was  to  DBGEN51  this 
Involves  the  posting  of  the  caller's 
parameter  list.  The  program  then  returns  to 
the  caller, 

CODING  SPECIEICATIONS 

1,  Source  Language 

This  module  is  written  using  the  TSS  360  Pl/I 
Language, 

2,.  Suggestions  and  Techniques 
Hot  Applicable 


Figure  2.  Top  Level  Flowchart  - DBGENR,  DBGENRl 
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TOPIC  P.10  - RETRIEVAL  POEHST  COHHAND 


A.  HODDLE  NAME 

Retrieval,  PORMAT  Cominaad 
Program-ID  - REBIOEH 

Hodule-ID  - .DBPORB.  Entry  points;  DBPORH  (primary) 
and  DEFORM  (for  PAGEing  a format  PISPIAY) . 

B,  ANALYST 

Garth  B.  Wyman 
Neot erics , Inc. 

C,  HODULE  FUNCTION 

The  DBFOSM  module  is  the  FORMAT  command  routine,  called 
by  the  RETRIEVEal  system,  whose  purpose  is  to  allow  the 
retrieval  system  user  to  define,  revise  and/or  display 
the  content  and  format  for  subsequent  information 
retrievals  using  the  DISPLAY  or  PRINT  retrieval 

commands.  Sequential  and  .columnar  formats  may  be 
defined. 

Sequential  formats  extend  the  series  of  predefined 
formats  1-4  by  allowing  the  user  to  select  a set  of 
fields  to  be  displayed  one  under  another  with  no  more 
than  one  record*s  fields  per  output  page. 

Columnar  formats  are  a separate  series  allowing  the 
user  to  select  a set  of  fields  to  be  displayed  in 
tabular  format.  Optionally,  the  user  may  define  screen 
or  printer  output,  page  numbering,  titles,  column 
headers,  column  positions,  and  element  tallying, 
summing  and  averaging. 

After  a current  format  has  been  established,  the  DBFORH 
module  functions  as  a command  director  processing  the 
FIELD,  FIELDS,  NAME,  STORE,  FORMATS,  DISPLAY,  PAGE, 
TITLE,  HEADER,  FORMAT  and  END  subcommands  of  the  FORMAT 
command. 

The  user  may  review  the  appearance  of  the  ultimate 
display  {paging  through  screen-width  portions,  if 
necessary).  The  user  has  complete  revision  and  storing 
capability. 

D.  DATA  REQUIREMENTS 

1,  I/O  Block  Diagram 
See  Figure  1 
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2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  , Punched  Card  Input  Files 

Hot  applicable 

c.  Input  Files 
Hot  applicable 

d.  On-line  Terminal  Entries 

A terminal  is  the  most  likely  source  of  the 
parameters  vhich  are  passed  to  the  FOEHAT 
command  by  the  Terminal  Support  system.  The 
fundamental  parameters  are  the  format  number 
and  the  field  names.  Default  values  for  the 
fundamental  parameters  are  unlikely.  The 
FOEHAT  command  then  accepts  the  FOEMAT 
subcommands  and  their  parameters, 

3,  Output  Data  Sets 

a.  Output  Files 
Hot  Applicable 

b.  On-line  Terminal  Displays 

For  sequential  formats,  the  DISPXAY 
subcommand  uill  display  the  field  names 
vertically  in  the  order  they  will  ultimately 
be  displayed.  The  PAGE  subcommand  will 
display  any  field  names  that  do  not  appear  on 
the  first  screen. 

For  columnar  formats,  the  DISPLAY  subcommand 
will  display  the  title  and  header  values  and 
field  column  positions  as  they  will 
ultimately  be  displayed.  In  the  case  of 
printer  formats  wider  than  the  display 

screen,  the  left-most  portion  will  be 
displayed  initially.  The  PAGE  sub-command 
will  display  subsequent  portions.  These 
displays  will  show  the  positioning  and  length 
of  the  field  values  for  the  first  data  line; 
ctherwise,  they  have  the  same  format  as  the 
DISPLAY  and  PRINT  retrieval  commands  produce 
(see  Section  III,  Topic  F,  4 of  the  DWE) , 
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c,  rormatted  Print-outs 
Hot  applicable 

a.  Punched  Card  Output  Piles 
Not  Applicable 
4«  Heference  Tables 

a.  C0L_P0PH 

When  ■ the  POEBAT  command  processes  a new 
columnar  format,  it  allocates  and  initializes 
a COL_?OEH  structure  and  posts  its  base 
address  in  the  COL_PORHaT  array  in  PLDTAB, 
When  the  POEMAT  command  processes  a TITIE  or 
HEADE5  sub-command  or  any  other  revision  to  a 
columnar  format,  it  updates  the  appropriate 
C01_P0EH  structure.  Thus,  a COL_POBH 
structure  specifies  a columnar  format  for  use 
by  the  DISPIAI  and  PRINT  commands. 

b.  PIDTAB 

The  POEHAT  command  refers  to  the  DATA  BASE 
and  PIEID  portions  of  PLDTAB  for  descriptor 
information  previously  posted  by  EDBINIT. 
The  POEHAT  command  posts  the  SEQ^POEHAT  and 
COl^POEMAT  arrays  as  it  processes  new 
formats. 

c.  SEQ_P0EM 

Hhen  the  POEHAT  command  processes  a new 
sequential  format,  it  allocates  and 
initializes  a SEQ__F0SH  structure  and  posts 
its  base  address  and  field  name  count  in  the 
SEQ_POEHAT  array  in  PLDTAB.  Thus,  a SBQ^PORH 
structure  specifies  a sequential  format  for 
use  hy  the  DISPLAY  and  PRINT  commands. 

d.  OSERTAB 

The  POEHAT  command  checks  the 
USEETAB.BETEIE7E  switch  to  verify  that  it  is 
being  called  properly. 

PROCESSING  EEQDIEEHENTS 

1.  Top  Level  Plowchart 

See  Pigure  2 
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Narrative 

a, . format 

3;he  EOEKAT  command  is  recognized  by  the 
retrieval  system  director  module  KDBINIT 
■Hhich  calls  the  DBFOEM  entry  point* 

b*  Process  INDtJBEl  parameter 

If  nail  or  blanks  are  entered,  the  EOEMAT 
command  is  cancelled,  The  value  is  checked 
for  proper  syntax  and  for  range  and 

duplication  of  the  number;  errors  are 

diagnosed  and  the  user  alloued  to  re-enter* 
If  the  value  is  a name,  the  external  GETSEHT 
routine  is  called  to  obtain  the  stored 

format.  For  a'  neu  format,  a SSQ_POR}!  or 
C0L_F0EI3  structure  is  allocated  and 
initialized  according  to  given  and  default 
options  and  the  structure’s  base  address 
posted  in  FXDTAB,  For  a revised  columnar 
format,  any  options  given  will  result  in  the 
COI_FORH  structure  being  modified  or 
re-allocated  and  initialized  accordingly* 
Removal  of  page  numbering  may  be  specified 
anS/or  expansion  to  printer  width  or 
contraction  to  screen  width.  If  the  width 
changes,  any  titles  are  re-centered.  If  the 
width  changes  and  the  columns  are 
proportional,  they  are  re-proportioned  and 
their  headers  (if  any)  re-centered.  If  the 
width  expands  and  the  columns  are  explicit, 
the  rightmost  column  will  have  its  width 
expanded  and  its  headers  (if  any) 

re-centered.  If  the  width  contracts  and  the 
columns  are  explicit,  columns  to  the  right  of 
a screen  width  are  dropped  from  the  format 
with  their  headers  (if  any)  and  the  remaining 
rightmost  column  will  have  its  width  reduced 
and  its  headers  (if  any)  re-centered. 


If  a FLDSPEC  parameter  was  entered  explicitly 
by  the  user  with  the  FOStJAT  command,  control 
passes  to  (d,)  below  where  the  parameter  is 
processed.  Otherwise,  processing  continues 
at  (c.)  . 

c.  Process  subcommand 

A command  is  obtained  from  the  Terminal 
Support  system.  If  it  is  a valid  FORMAT 
subcommand,  it  is  processed  by  one  of  the 


PAGE  482 


roTitines  <d,)  through  (k.)  below.  Otherwise, 
it  is  diagnosed  as  an  invalid  subcommand  and 
the  user  allowed  to  re-enter. . 

d.  Process  IIEID  command 

The  field  names  are  checked  for  existence  in 
the  current  data  base  by  lookup  in  the  FIEID 
portion  of  ILDTAB,  If  a field  name  or 
porition  is  invalid,  a diagnostic  is  issued 
and  the  keyboard  unlocked  for  re-entry  of 
that  field  name  with  any  options  or  default 
for  that  field  to  be  ignored,  Normally,  for 
sueguential  formats,  the  field-  name  is  posted 
in  SEQ^FOBH,  or  for  columnar  formats  the 
field  name,  position  (proportioned,  if  not 
specified  by  the  user)  and  options  are  posted 
or  updated  in  COL^FOBH. 

e.  Process  FIELDS  or  FOBfiJTS  command 

These  commands  are  recognized  as  a 
convenience  to  the  user  to  save  him  having  to 
leave  FOEHAT  and  later  re-enter  it. 
Processing  consists  only  of  a call  to  the 
external  entry  point  DBFLDS  or  DBSTET2 
respectively, 

f.  Process  NAME  or  STOEE  command 

An  FMTNAME  parameter  value  is  obtained  from 
the  Terminal  Support  system,  validated 
syntactically  by  calling  the  external  DBUCHEK 
routine,  and  checked  for  duplication  of  the 
name  of  any  other  current  format.  For  a NAME 
command,  the  value  is  simply  posted  in 
FLDTAB,  For  a STOB.E  command,  the  value  is 
posted  in  FLDTAB  or  it  is  verified  that  a 
name  value  was  posted  there  previously  and 
the  external  PDTSFMT  routine  is  called  to 
store  the  format  for  availability  in  later 
sessions.  If  the  FETNAHE  value  is  invalid  or 
missing  or  if  PDTSFMT  returns  an  error  code, 
a diagnostic  is  issued  and  the  user  allowed 
to  re-enter  it, 

g.  Process  TITLE  command 

If  the  current  format  is  not  columnar,  the 
TITLE  command  is  cancelled  with  a diagnostic 
message, 

A TTLLINE  parameter  value  is  obtained  from 
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the  Terntinal  Support  system,  if  the  user 
entered  it  explicitly,  or  by  assuming  the 
next  relative  title  line  nnmber.  The  value 
is  checked  for  syntax,  range,  duplication, 
and  space  in  COL__FOBU,  TOP.  hny  error  is 
diagnosed  and  the  user  allowed  to  re-enter 
the  parameter.  For  a title  line  deletion, 
any  lower  title  and  header  line  images  are 
shifted  up  and  C01_F0BM,T0P.#TITLES  is 
decremented  and  control  branches  to  (c»). 
For  a new  title  line,  any  lower  title  and 
header  line  images  are  shifted  down  and 
intervening  lines  blanked  in 
COX_FOBa. TOP. LINE  and  COl^FOHE , TOP . #TIT1ES  is 
posted. 

A TTLSPEC  parameter  value  is  obtained  from 
the  Terminal  Support  system,  if  the  user 
entered  it  explicitly,  or  by  taking  the 
FLDThB.raTA  BASE  name  value  and  stripping  any 
trailing  dollar  sign  characters.  The  value 
is  posted  centered  in  the  particular 
C01_F0BE.T0P.1IWE, 

Process  BEAPIB  command 

If  the  current  format  is  not  columnar,  the 
HEADEB  command  is  cancelled  with  a diagnostic 
message. 

A BDBIINE  parameter  value  is  obtained  from 
the  Terminal  Support  system,  if  the  user 
entered  it  explicitly,  or  by  assuming  the 
next  relative  header  line  number.  The  value 
is  checked  for  syntax,  range,  duplication, 
and  space  in  CCL_F0BH,T0P.  Any  error  is 
diangosed  and  the  user  allowed  to  re-enter 
the  parameter.  For  a header  line  deletion, 
any  lower  header  line  images  are  shifted  up 
and  C0L_F0EK. T0P#HEADEES  is  decremented  and 
control  branches  to  fc.).  For  a new  header 
line,  any  lower  header  line  images  are 
shifted  down  and  intervening  lines  blanked  in 
C0I_F0HE. TOP, LINE  and  C01_F0BH. TOP. #HEADEBS 
is  posted.  Thus  a current  header  line  is 
determined  for  the  following  processing. 

If  no  HBBSPEC  parameter  values  were  entered 
explicitly  by  the  user,  every  column  accross 
the  current  header  line  has  its  field  name 
value  centered  over  it  and  control  branches 
to  (c . ) . 
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Cther'Hise,  HDBSPEC  parameter  values  are 
obtained  one  by  one  from  the  Terminal  Support 
system  and  processed  individually.  If  only  a 
literal  value  is  given,  it  is  centered  over 
the  next  column  to  the  right.  If  only  a 
parenthesized  field  name  is  given,  it  is 
centered  over  the  column  for  the  field 
name.  If  both  a literal  value  and  a 
parenthesized  field  name  are  given,  the  value 
is  centered  over  the  column  for  the  specified 
field  name.  Any  syntax,  field  name,  or  past 
rightmost  column  error  results  in  a 
diagnostic  message  allowing  the  user  to 
re-enter  one  value  or  to  default  for  "that 
value  to  be  ignored. 

i.  Process  BISPlAl  command 

The  display  simulates  the  appearance  produced 
by  the  retrieval  system  DISPLAI  command  if  it 
was  used  with  the  current  formai:. 

If  a sequential  format  display  overflows  the 
screen  at  the  bottom  or  if  a columnar  format 
display  overflows  the  screen  at  the  right 
side,  ’'MOEE’*  is  indicated  and  the  Terminal 
Support  ' system  is  requested  to  call  DBFOEHP 
if  the  user  enters  the  PAGE  immediate 
command.  . 

Hhen  the  module  is  entered  at  the  DBEOEHP 
paging  entry  a DIEECTON  parameter  value  is 
obtained  from  the  Terminal  Support  system,  if 
the  use.r  entered  it  explicitly.  or  by 
assuming  forward  paging.  If  the  value,  starts 
with  ’*B”  the  previous  display  screen  image  is' 
re-composed,  otherwise  the  next  display 
screen  image  (down  or  to  the  right)  is 
composed.  Screen  overflow  is  rechecked  to 
reset  the  indication  and  the  Terminal 
Support  system  transmits  the  screen  image  to 
the  user’s  terminal. 

j.  lOBHAT  command 

If  ’’POBBAT”  is  detected  as  a sub-command, 
control  simply  branches  up  to  (b.)  where  its 
parameters  are  obtained  and  it  is  processed. 
(This  is  more  efficient  than  "EBDjEOBMAT” 
because  the  DBFOBH  module  stays  active.) 


Tc 


END  command;  EETDEN 
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If  tfie  END  condition  is  raised  by  the  user 
entering  the  END  immediate  command  in  blocks 
(a.)  or  (h,),  control  returns  -to  the  BDBINIT 
module.  If  it  is  raised  after  block  (b.) 
control  branches  to  block  (c, ) , that  is,  the 
subcommand  is  aborted  and  another  taken, 

3,  Submodules  required 

DBFIDS  - EIEIIS  command 
DBSTBT2  - EOEHATS  command 
DBDCHEK  check  name  routine 
GETSFHT  - get  stored  format 
PDTSFHT  - put  stored  format 
PSTBAT  - save  strategy 
IS  terminal  support  package 

CODING  SPECIFICATIONS 

1.  Source  language 

The  FOIHAT  command  is  coded  in  TSS  PL/I,  The 
TSPL/I  language  extension  is  used  for  all 
communication  uith  the  terminal, 

2,  Suggestions  and  Techniques 

The  PSTBAT  external  routine  shall  be  called 
whenever  a valid  command  or  subcommand  with  “valid 
parameters  is  detected. 

Subroutine  facilities  shall  be  coded  to  handle  the 
general  case  of  re-proportioning  columns  and 

re-centering  headers,  (DDP_COL,  EE_PBO_COL, 

8E_BEAD)  . 
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TOPIC  P,  11  STOHED  EOEHATS 

A.  HOBUXE  WaME 

Program-IB  - BDBSEBT 
0Odule-ID  - BBSFMT 

B.  - ABALYST 

John  A,  I-ozan 
Beoterics,  Inc. 

C.  BOBBLE  rUNCTION 

The  function  of  this  tDcdule  is  to  provide  generalized 
GET/PBT  routines  for  the  processing  of  stored 
formats, 

B.  DATA  EEQDIEEHEKTS 

1,  - I/O  Block  Diagram 

See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Mot  Applicable 

b.  Punched  Card  Input  File 
Not  Applicable 

c.  Input  Files 
Mot  Applicable 

d.  On-time  terminal  Entries 
Sot  Applicable 

3*  Output  Data  Sets 

a.  Output  liles 
Mot  Applicable 

b,  On-Line  Terminal  Displays 

The  program  produces  diagnostic  messages  for 
the  various  errors  that  may  occur. 
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c. . lormat±€a  Print  Outs 
Kot  Applicable 

d»  Punched  Card  Output  Piles 
Not  Applicable 

4*  Reference  Tables 

The  following  tables  are  referenced,  used  in  the 
construction  of  new  formats  and  used  to  output 
exiting  formats. 

FLDTAE 

SEQFOBH 

COIPOSH 

PROCESSING  REQUIREMINTS 

1.  Top  level  Elowchart 
See  Figure  2 

2.  Narrative 

a.  GETSFHT 

At  this  entry  point  the  program  initialises 
itself  to  read  in  a previously-stored  format. 
It  verifies  the  name  of  the  format  and  checks 
to  see  if  the  format  is  already  in  the  format 
table.  If  so,  the  program  returns 

immediately  with  the  appropriate 

information. 

If  the  format  must  be  read,  the  first  record 
of  the  format  is  obtained  by  calling  TSSETEG, 
This  record  is  analyzed  to  determine  if  the 
format  is  columnar  or  sequential.  The 
appropriate  format  tables  are-  then  searched 
for  a slot  into  which  the  format  can  be 
placed  and  the  format  is  allocated  and 

initialized. 

The  program  then  obtains  the  remaining  format 
records  and  posts  the  data  obtained  into  the 
appropriate  locations  within  the  format 
entry.  If  any  errors  are  encountered,  an 
appropriate  diagnostic  message  is  written  to 
the  user  and  the  partial  format  is  freed. 
After  an  error,  or  when  the  format  has  been 
completed,  the  required  information  is 


PAGE  490 


updated  and  the  program  returns  to  the 
caller. 

b.  PDTSrHT 

it  this  entry  point  the  program  initializes 
itself  to  write  out  one  of  the  currently 
defined  formats.  It  verifies  the  name  of  the 
format  and  checks  to  see  of  the  format  exists 
in  the  format  tables.  If  not,  the  program 
terminates  with  a diagnostic* 

If  everything  Is  in  order,  the  program 
constructs  the  first  format  record  (FO'RHAT)  , 
indicating  the  format  name,  type,  the 
intended  file  name  and  .other  descriptive 
information  and  writes  it  to  the  data  set  by 
calling  ISPUIEG. 

The  remaining  format  data  is  organized  into 
TITIE,  EEADES  and  FIELDS  records  and  written 
to  the  data  SET  in  the  same  fashion  as  the 
FOEHAT  record.  If  any  errors  are 
encountered,  an  appropriate  diagnostic 
message  is  written  to  the  user  and  the 
partially  stored  format  is  erased,  . After  an 
error,  or  when  the  format  has  been  completely 
written  out,  the  required  information  is 
posted  and  the  program  returns  to  the 
caller. 

CODING  SPECIFICATIONS 

1,  Source  language 

The  module  is  written  using  the  TSS  360  Pl/I 
Language. 

2,  Suggestions  and  Techniques 
Not  Applicable 


Figure  1. 


I/O  Block  Diagram 
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TOPIC  F, 12  - GEHEEIC  KEY  DISPLAY 

MODDLE  IJAHE 

Program-ID  - rdbgfi-DS 
Moaule-ID  - DBGFLDS 

B.  ANALYST 

John  A.  Lozan 
Neoterics,  Inc. 

C.  MODULE  FUNCTION 

This  Hiodnle  displays  a formatted  listing  of  the  names 
assigned  to  the  snt-levels  of  the  key  for  a generic  key 
file. 

D.  DATA  REQUIBEMENTS 

1.  I/O  Block  Diagram 
See  Fignre  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

h.  Punched  Card  Input  Files 
Not  Applicable 

c,  . Input  Files 

Not  Applicable 

d.  On-Line  Terminal  Entries 
Not  Applicable 

3.  Outpuf  Data  Sets 

a.  Output  files 
Hot  Applicable 

b.  On-Line  Terminal  Displays 

The  program  produces  a formatted  list-'-  of  the 
sub-level  names. 
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c,  Ecrmatted  Print  Oats 
Kot  Applicable 

a.  Punched  Card  Output  Piles 
Hot  Applicable 
'4«  Reference  Tables 

The  program  references  the  following  tables  to 
obtain  the  information  which  it  displays, 

FIBTAB 

GENERIC 

PROCESSING  HEQTJIEENENTS 

1.  Top  Level  Flowchart 
See  Figure  2 

2.  , Narrative 

Upon  entry  the  program  initiali'zes  the  screen  and 
other  data  necessary  to  construct  the  display.  It 
extracts  the  current  file  name  from  FLDTAB  and 
uses  it  to  construct  the  generic  table  definition 
routine  ( XXXXIXX,  where  xxxxxx  is  the  file  name). 
It  calls  this  routine  to  obtain  the  generic  key 
description.  If  any  errors  are  indicated,  a 
diagnostic  message  is  written  to  the  user  and  the 
program  is  terminated. 

The  program  then  extracts  each  name  from  the 
generic  key  description  table  and  posts  is  to  the 
screen.  When  the  list  is  exhausted,  the  screen  is 
displayed  to  the  user  and  the  program  returns  to 
the  caller, 

CODING  SPECIFICATIONS 

1,  Source  Language 

The  module  is  written  using  the  TSS  360  PL/I 
language. 

2,  Suggestions  and  Techniques 
Not  Applicable 
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Figure  1.  I/O  Block  Diagram 
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NASIS  STRATEGY,  DATASET 


Fig.  1 I/O  Block  Diagram 
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Figure  2.  Top  Level  Flowchart  - DBGFLDS 


FIG.  2 TOP  LEVEL  PLOV/CHAET 
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TOPIC  - BATCH  PSIHT  KOHITOB 

A.  MODULE  MAMI 

Program  - ID  - EDHPIilliT 
Module  - IE  - DBPBIIIT 

B.  ANALYST 

Franl?  Heed 
Neot erics,  Inc. 

C.  MODULE  PUNCTION 

This  program  controls  the  execution  of  the  batch  print 
system  in  much  the  same  say  that  HDBINIT  controls  the 
retrieval  system.  That  is,  it  initializes  file-related 
tables  and  issues  command  prompts  to  activate  batch 
sub-system  cperaticns. 

D.  DATA  REQUIEEMENT-S 

1.  I/O  Block  Diagram 
See  Figure  1. 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
BASIS. USERIDS 

d.  On-line  Terminal  Entries 

The  user  of  the  batch  print  system 
communicates  with  the  system  through  a series 
of  command  and  data  prompts.  The  commands 
and  parameters  are: 

1,  END 

Terminate  the  terminal  session 

2.  PRINT  NAsisiB=,BSN= 
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ProSace  a formatted  print-out  of  data  from  a file 
utilizing  information  saved  in  the  print  gaeue  for 
Nasis  ID  «ith  Batch  seguence  Humber  (BSN) 
specified. 

3.  HOLD  HASISID=,BSH= 

Place  a print  job  in  “hold”  status, 

4.  RELEASE  NASisID=,BSH= 

Place  a print  job  in  ‘'active”  status  so  that  it 
can  be  executed. 

5.  EXHIBIT  HASISID=,BSH= 

Display  a formatted  description  of  the  contents  of 
the  batch  print  queue  at  the  user’s  terminal. 

8.  NHMBES  HASISID= 

Tally  the  'number  of  print  tasks  in  the  queue. 

7.  CAHCEl  NASISID=,ESH= 

Remove  a print  task  from  the  queue, 

8.  KEYS  HASISID=,BSH- 

Display  the  file  name  and  record  keys  recorded  for 
a print  task. 

9.  COPIES  HASISID=,BSN=,COPIES= 

Overide  the  user  specified  value  for  number  of 
copies  of  a printed  report, 

3,  Output  Data  Sets 

a.  Output  Piles 
Hot  Applicable 

b.  On-line  Terminal  Displays 
Hot  Applicable 

c.  Formatted  Print-outs 
Hot  Applicable 

d.  Punched  Card  Output  Files 
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Not  Applicable 
4.  Beference  Tables 
Not  Applicable 

E.  . PROCESSING  BEQtJIBEHENTS 

1.  Top  level  Flowcharts 
See  Figure  2, 

2,  Narrative 

DBPBIHT  gets  control  from  DBMTT,  then  prompts  for 
one  of  the  ccmmanas  outlined  in  section  2D.  If 
the  command  is  PRINT,  the  information  relating  to 
the  user’s  print  gueue  is  retrieved  from  the 
strategy  data  set  and  used  to  open  the  file  from 
which  data  is  to  be  printed.  After  all 
initialization  is  complete,  control  is  passed  to 
DBNBIT  to  perform  the  actual  data  retrieval  and 
printing. 

All  other  commands  provide  various  operations  on 
the  user’s  print  gueue  as  described  above,  except 
END,  which  returns  control  to  DBHTT, 

F,  CODING  SPECIFICATIONS 
1,  Source  language 

PL/I 

Suggestions  and  Technigues 
Not  Applicable 


2. 
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TOPIC  - BATCH  PBIHT  HBITEE 

-A.  HODTJLE  MAHI 

Program  - ID  - BDBBEIT 
Hodule  - IE  - BBEBIT 

B.  ANALYST 

Frank  Bee3 
Neoterlcs,  Inc. 

C.  MODULE  FUNCTION 

This  program  retrieves  data  from  a user  - specified 
data  base  and  prints  a listing  in  either  a predefined 
seguential  format  or  a user~defined  sequential  or 
columnar  format. 

D.  DATA  BEQUIBEMENTS 

1.  I/O  Block  Diagram 
See  Figure  1, 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c«  Input  Files 

Any  NASIS  data  base, 
d,  , Gn-line  Terminal  Entries 
None 

3.  Output  Data  Sets 

a.  Output  Files 

Print  file  (PHINTEB) 

b.  On-line  Terminal  Displays 
Net  Applicable 


PAGE  501 


c*  Eorm'ali-tea  Print  Outs 

User  - aefined  segnential  or  coltimnar 
prints. 

a.  PuncKad  Card  Output  Piles 
Not  Applicable 
4.  Reference  Tables 
Not  Applicable 
PROCESSING  REQUIEEKENTS 

1.  Top  level  Plovcharts 
See  Pigure  2. 

2.  Narrative 

3BNRIT  gets  control  from  DBPBINT,  then  opens  the 
PRINTER  output  file  and  creates  the  title  page. 
Next,  a xecoid  from  the  data  base  being  retrieved 
from  is  read  and  either  sequential  or  columnar 
formatting  is  begun  based  on  a table  of  field 
names  specified  by  the  user.  Por  sequential 
formats,  the  field  names  and  associated  data  are 
displayed  on  successive  lines  -with  the  field  names 
to  the  left  of  the  data.  Columnar  formats  require 
the  printing  of  header  and  title  information 
(saved  by  the  PRINT  and  PORHAT  functions)  along 
ijith  the  field  names  or  other  identifier  for  each 
column  of  data  across  the  top  of  each  page.  The 
data  for  each  field  is  presented  under  the 
appropriate  column  heading  until  the  list  of 
record  keys  is  exhausted. 

When  all  printing  of  data  is  completed,  a summary 
of  informaticn  contained  therein  is  displayed. 
Eor  sequential  prints  this  is  simply  a count  of 
the  number  cf  records  displayed.  Por  columnar 
prints,  this  can  be,  optionally,  a tally,  sum,  and 
average  of  the  numerical  values  of  items  occurring 
in  one  or  more  of  the  columns. 

After  closing  the  PRINTER  file,  control  is 
returned  to  DBPRINT  with  a return  code  of  *X*  for 
a print  terminated  by  the  operator  of  *0*  for  a 
print  terminated  by  a data  base  error.  The  return 
code  is  unchanged  if  the  print  completes 
successfully. 


CODIKG  SPECIFICATIOHS 
1.  Source  Language 
PL/I 

Suggestions  and  Techniques 
Hot  Applicable 


2 


FIGURE  1 I/O  BLOCK  DIAGRAM 


,T=^. 


FIGURE  2 


TOP  LEVEL  FLOWCHART 
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TOPIC  F.  15  - XI KIT  ComiRana 

A.  MODULE  SAMI 

Eetrieval  LIMIT  Ccmniana 
Program-ID  - edblkt 
Hodule-IB  - DBLMT 

B.  AKALYST 

Barry  6.  Hazlett 
Neoterics,  Ire. 

C.  MODULE  FUNCTION 

This  ooflule  limits  an  existing  set  of  anchor  file  keys 
according  to  the  specified  criteria  thereby  creating  a 
new  set. 

D.  DATA  lEQUIDE RENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Not  Applicable 

d.  On-Line  Terminal  Entries 
Not  Applicable 

3.  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-Line  Terminal  Displays 

The  new  set  created  by  the  LIMIT  command  is 
displayed  on  the  output  screen  through  use  of 
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the  routine  DBPSET,  Befer  to  the  dataset 
specification  section  of  .the  DWB  for  a 
writeup  cf  this  display. 

c.  Eormatted  Print-Outs 

Not  Applicable 

PEOCESSING  BIQUISEHENTS 

1.  Top  Level  Plowchart 
See  Eigure  2 

2.  Narrative 

Opon  entry  into  DBLHT,  of  the  LIMIT  structure  has 
not  been  allocated,  a module  name  is  derived  by 
concatenating  ”L”  to  the  data  base  name.  If  ~the 
module  does  not-  exist,  the  user  is  given  a 
diagnostic  and  control  is  returned  to  the  calling 
routine. 

After  determining  a valid  LIMIT  structure  exists, 
the  user  is  prompted  for  the  set  to  be  limited. 
To  be  valid  the  set  must  exist  and  mnst  consist  of 
anchor  file  heys.  If  the  set  number  is  invalid, 
the  user  is  given  a diagnostic  and  prompted  for  a 
new  set  number. 

After  obtaining  a valid  set  number,  the  user  is 
prompted  for  a list  of  limits  to  apply  against  the 
set.  To  be  valid  the  specified  fieldname  must  be 
present  in  the  LIMIT  table  and  the  values  must  be 
less  than  51  characters  long  and  the  two  values 
must  be  separated  by  a colon.  If  the  limit  is 
invalid  the  user  is  given  a diagnostic  and 
reprompted  for  the  limit.  If  the  limit  is  valid, 
a flag  is  set  in  LIMIT  indicating  which  subfield 
to  test  along  with  the  two  values  indicating  the 
value  range.  If  more  limits  are  in  the  input 
streem,  tbey  are  prompted  for  and  processed  as 
above. 

Once  all  of  the  limit  criteria  have  been 
established,  a control  loop  is  setup  to  obtain 
the  keys  cne  by  one  from  the  input  set.  Each 
subfield  to  be  tested  is  extracted  from  the  key 
and  compared  against  the  acceptable  values  for 
this  field.  If  a key  fails  any  of  the  specified 
tests,  it  is  ignored  and  the  next  key  from  the 
list  is  obtained  and  processed  as  above.  If  the 
key  is  acceptable,  it  is  posted  in  a new  list. 
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After  all  the  keys  in  the  input  list  have  been 
processed,  the  new  set  is  posted  in  SETAB  and  the 
results  posted  to  the  user  screen  through  use  of 
the  routine  DBPSET,  after  which  control  is 
returned  to  the  calling  program. 

CODING  SPECITICATICNS 

1,  Source  language 

IBH/360  Pl/I  language 

Suggestions  and  lechnigues 

Not  Applicable 


2 


\ 


-5> 
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TOPIC  G. 1 - ACCUaOlATIGN 

A,  HODOEE  NAME 

Statistics  AccuBTilator 
Program-ID  - BDBACCUH 
Module-TD  - DBACCOH 

B.  . ANALYST 

James  A.  Wesley 
Neoterics,  Inc* 

C.  MODULE  FUNCTION 

Primarily » tfis  module  is  used  to  accumulate  the 
mainteuauce  statistics  on  those  data  bases  "which  have 
already  been  loaded. 

This  program  reads  an  existing  data  base  anchor  file 
and  accumulates  the  number  of  records  on  it.  Then,  it 
posts  this  record  count  to  the  STATIC  data  base, 

D,  DATA  REQDIEEMENTS 

1,  I/O  Block  Diagram 
See  Figure"  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  data  base  ^hich  is  to  have  the  statistics 
accumulated,  and  the  STATIC  dataplex, 

d.  On-line  Terminal  Entries 
Not  Applicable 
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3.  OTitpiit  Data  Sets 

a.  Output  Files 

The  STATIC  Dataplex 

b.  Cn-line  Terminal  Displays 
Not  Applicable 

c.  lormattecl  Drint-outs 
Not  applicable 

4*  Reference  Tables 
Not  Applicable 
DEOCESSING  BIQOIEEHENTS 

1,  Top  level  flowchart 
See  Figure  2 

2.  Narrative 
Error  Bessage; 

EBEOE  ON  $01  OF  $02. 

Where; 

$01  is  the  OHFIIE, 

$02  is  the  ONCODE. 

The  program  trill  accept  -the  data  base  name  as  a 
parameter  and  will  proceed  to  count  the  anchor 
files  records.  When  this  task  is  completed,  it 
will  open  the  STATIC  data  base  for  update  and  post 
the  record  count. 

The  posting  of  the  STATIC  data  base  assumes  that 
no  record  for  this  data  base  currently  exists. 
Therefore,  if  - an  error  occurs  on  the  LOCATE 
Statement  for  the  posting,  the  job  is 
terminated.  The  key*s  value  for  the  locate 
statement  is  as  follows: 

A value  of  *0’  concatenated  to  the  data  base 
name  and  filled  with  $*s  to  24  characters. 

The  field  »ANCOONT*  is  posted  -with  the  number 
of  anchor  records. 
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The  field  * HAINDATE  (1) * is  posted  with  the 
jobs  run  date,  i«e. , this  is  assumed  to  be 
the  creation  date  for  statistics. 

The  field  * TOTAL  BON*  is  posted  with  a *1*. 

The  field  *TBANCNEfl*  is  posted  with  the 
number  of  anchor  records. 

The  following  fields  are  posted  to  *0*5 
»T-0TALTBN*,  ‘TRANCDEL*  , *TBASC0PD«, 

’TEIB-VSEl* , ’TEINVDEL*,  and  ‘TEINVOPL*. 

E,  . CODING  SPEICIECATIOHS 

1, , Source  language 

The  BDBACCD.N  module  is  coded  in  the  IBM 

programming  language  PL/I,  The  DBPL/T  and  TSPL/I 
language  extensions  are  used  for  data  base  access 
and  terminal  I/O,  respectively, 

2,  Suggestions  and  Technigues 

It  is  important  to  remember  that  the  executive 
error  *99*  indicates  an  end  of  file  condition. 
Special  attention  is  made  for  the  handling  of  the 
data  base  executive  errors. 
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TOPIC  G,2  - EEPOPT  PBINT 

A.  HODniE  HAMI 

Print  the  Eetrieval  Statistics 
Program-ID  - EDHFBKTB 
Hodule-IE  - DEPEHT-S 

B.  ANAIYST 

Edward  J.  Scheboth , dr* 

James  A.  Wesley 
Neoterics,  Inc* 

C.  HODBIE  TDWCIIOK 

The  purpose  of  this  program  is  to  present  a detailed 
listing  of  the  contents  of  the  STATIC  data  base 
pertaining  to  retrieval  statistics* 

D.  BATA  REQOIBEHENTS 

1,  I/O  Bloch  Diagram 
see  Pigure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Kot  Applicable 

b.  Punched  Card  Input  Piles 
Not  Applicable 

c.  Input  Files 

The  STATIC  data  base,  (for  full  details  on 
this  data  base  see  Section  III  of  the 
Development  Workbook) . 

d.  On-line  Terminal  Entries 
Not  Applicable 

3*  Output  Data  Sets 
a.  Output  Piles 

Not  Applicable 
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b.  On-line  terminal  Displays 
Hot  Applicable 

c.  . Eormatted  Print-outs 

The  retrieval  statistics*  report,  (for  full 
details  of  this  report  (listing)  see  Section 
III  of  the  Development  Horkbook) * 

4,  Reference  Tables 

Hot  Applicable 

E,  PBOCESSING  EEQUIEEHENTS 

1.  Flowchart 

See  Figure  2 

2,  Narrative 

This  module  performs  the  following  logic  in  order 

to  produce  the  retrieval  statistics*  report 

a.  Open  the  STATIC  data  base  for  sequential 
input  (use  DBPL/I)  * 

b.  Bead  the  STATIC  file  sequentially  record  by 
record  and  while  reading,  construct  from  the 
current  information  on  the  STATIC  data  base 
the  required  listing, 

c«  Output  the  print  file  required  to  produce  the 
retrieval  statistics'  report. 

d.  Close  all  files:  Terminate, 

Note;  It  will  be  necessary  for  this  program  to 
accumulate  various  information  so  that  it 
can  output  the  summary  of  retrieval 

statistics,  representing  all  of  the 
statistics  on  the  STATIC  data  base. 


P,  CODING  SPECIFICATIONS 
1,  Source  language 

The  EDBPBNTB  module  is  coded  in  the  IBM 
programming  language  PL/I,  The  DBPL/I  and  TSPL/I 
language  extensions  are  used  for  data  base  access 
and  terminal  I/O,  respectively. 
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Suggestions  anfl  Slechnigues 

Eefer  to  Section  III  of  the  Development  Workbook 
fox  all  data  set  specifications  and  all  data  base 
executive  errors. 


Figu  re  1,  1 10  Block  diag  ra  m 
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TOPIC  G.3  - OSAGE  STATISTICS  UPDATE 


A.  . HODUEE  NAME 

Update  Maintenance  Statistics 
Program-ID  - RDBUPDST 
Module-ID  - DBUPDSI 

B.  ANALYST 

Edward  Schehoth,  Jr. 

James  A«  Wesley 
Neoterics,  Inc, 

C.  MODULE  EUNCTION 

This  program  updates  the  statistics  data  base  (STATIC) 
with  the  maintenance  statistics  from  the  load/create 
program  (RDBLOAD)  or  from  the  maintenance  mainline 
(EDBHNTN) , 

D.  DATA  SEQUIEEMENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  ' Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  STATIC  Dataplex 

d.  On-line  Terminal  Entries 
Not  Applicable 

3,  Output  Data  Sets 
a.  Output  Files 


The  STATIC  Data  Base 
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b*  On-line  Terminal  Displays 
Hot  Applicable 
c*  formatted  Print-onts 
Hot  applicable 
4,  ■ Beference  'Tables 
Not  Applicable 
PEOCESSING  BEQUIBEHENTS 

1.  Top  level  Flowchart 
See  Figure  2 

2,  Narrative 

The  parameters  are  passed  via  standard  PL/I 
procedure/prccedure  linkage  key  calls  from 
BDBMNTN  and  EEBLOAE. 

The  parameters  which  are  passed  are  as  follows: 

a.  Calling  program  identifier  character  2* 

First  Character 

C = first  call. 

M = subsequent  call.  — 

Second  character. 

X = called  from  LOAD, 

anything  else  signifies  - called  from 
elsewhere. 

b.  File  being  updated. 

c.  Number  cf  new  anchor  records,  character  6. 

d.  Number  of  deleted  anchor  records,  character 

6. 

e.  Number  of  updated  anchor  records,  character 

6. 

-f.  Number  of  new  subfield  records,  character  6. 

g.  Number  of  deleted  subfile  records,  character 

6. 

h.  Humber  cf  updated  subfile  records,  character 

6. 
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i.  Humber  of  ne-w  inverted  records,  character  6«  . 

j.  Humber  of  deleted  inverted  records,  character 

6. 

k.  Number  of  updated  inverted  records,  character 

6, 

The  load/create  module  (BDBLOAD)  invokes  this 
module  only  once,  and  this  is  at  the  end  of  the 
create  run.  Therefore,  this  module  opens  the 
STATIC  da±a  base  for  direct  (update  or  output)  and 
locates  the  new  record*  The  data  is  put  and  the 
file  closed. 

The  maintenance  mainline  (BDBHHTH)  is  calling  the 
module  continuously  while  processing  (this  is  to 
preclude  the  possibility  of  a system  crash  causing 
a loss  of  statistics).  Therefore,  upon  the  first 
invocation  from  the  maintenance  mainline,  the 
STATIC  data  base  is  opened  for  direct  update.  The 
proper  record  is  read  and  written,  and  control  is 
returned  to  the  maintenance  mainline. 

The  final  call  from  the  maintenance  mainline  will 
have  an  ’I*  posted  to  the  calling  program 
identifier. 

If  the  updating  of  the  STATIC  data  base  is 
successful,  a *G'  is  posted  to  the  calling 
program  identifier  upon  return;  whereas,  if  the 
results  are  not  successful,  a *B’  is  posted. 

If  the  results  of  the  attempted  posting  are  bad, 
the  calling  programs  will  resolve  the  disposition 
of  the  non-posted  data. 

The  details  of  the  contents  of  the  STATIC  data 
base  can  be  found  in  Section  III  of  the 
Development  Workbook, 

The  following  illustrates  the  parameters  passed 
and  -the  associated  fields  which  are  updated;  they 
are  in  the  form  ’‘parameter  - static  field  name”; 

a,  . Maintenance  date  - MAINDATE 

b.  Number  of  new  anchor  records  ^ TBANCNEW 

c,  Humber  of  deleted  - TEANCDEL 

d.  Number  of  update  ^ TRAHCDPD 
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e.  Kumiier  of  new  subfile  recoris  - THSUBNEW 

f.  Kunsber  of  deleted  - TBSOBDEL 

g.  Number  of  updated  - TBSUBOPD 

h.  Humber  of  ueu  inverted  records  - TRINVNES 

i.  Number  of  deleted  ~ 5JBIHVDEL 

j.  Humber  of  update  - TEIHVUPD  . 

k.  Calling  program  identifier  - *-none-* 

It  is  important  to  remember  that  there  is  a one 
for  one  correspondence  between  all  of  the 
previously  mentioned  STATIC  data  base  fields.  For 
E:Kample; 

If  HAIHDATE  ==  *03/16/70 » and  this  is  the 

actual  date  of  the  maintenance  run,  then  if 
the  MAIHDATE  value  of  *03/16/70 « is  the  third 
element  in  the  variable  length  field,  then 

all  updates  to  the  other  elemental  fields  of 
the  record  are  made  to  the  third  element* 

The  table  which  follows  will  help  to 
illustrate  this  more  clearly* 

EAINDATI  01/16/70  02/16/70  03/16/70  null 

TBANCNER  931 

TBAHCDEI  18  4 1 

TBANCUPD  371 

TBSOBHEW  791 

TBSDBBEX  3 12  6 

TBSUBDED  192 

TBIHVNEH  16  3 1 

TBIHVDEX  441 

TBINVUPE  12  7 1 

The  fields  we  are  concerned  with  are:  HAIHDATE, 

TEAHCHEB,  TBAKCDE1-,  TBSUBKEW,,  TESUBDEl,  TBSOBUPD, 
TBAHCUPD,  TBIHVNEH,  TRIHVDEL,  TRIHVUPD. 

These  fields  are  all  variable  length  fields  with 
multiple  fixed  length  elements*  The  maximum 
number  of  elements  is  13.  The  first  element  in 
the  array  is  used  as  an  accumulator.  Elements  2 
through  13  axe  used  to  represent  individual 
maintenance  runs. 

This  is  simple  enough — when  this  module  is'  called 
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from  IDBMNTN,  It  simply  locates  the  maindate  which 
is  the  same  as  the  parameter  and  does  the  posting 
into  that  given  element. 

The  question  is  whai  does  this  module  do  when  it’s 
called  for  the  first  time  from  the  maintenance 
program  (EBBfiillTN)  and  the  date  is  not  equal  to  any 
of  the  posted  dates  and  all  13  elements  have  data 
so  that  there  is  no  additional  elemental  slot 
where  the  data  can  he  placed. 

The  solution  is  as  follows;  first,  the  second 
elemental  slot  is  *EEPDT’  to  null,  Which  causes 
the  data  base  executive  to  automatically  slide  all 
of  the  other  elements  (logically).  Then,  the  new 
maintenance  data  will  be  ’PUT*  as  the  thirteenth 
element, 

CODING  SPECIfICATIGNS 
1,  Source .language 

The  BDEUPDST  module  is  coded  in  the  IBH 
programming  language  PL/I.  The  DBPL/I  and  TSPL/I 
language  extensions  are  used  for  data  base  access 
and  terminal  I/O,  respectively, 

2,.  Suggestions  and  Techniques 

Refer  to  Section  III  of  the  Development  Workbook 
for  all  data  set  specifications  and  all  data  base 
executive  errors. 


STATIC 

DATAPLEX 
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Figure  2.  Top  level  flowchart 
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TOPIC  G.4  - CLOCK  SOUIIKES 

a.  HODULE  KAME 

Clock  Soutines 
Program-ID  - EIIHEES 
Module-ID  - BTIMEPS 

B,  AKAXYST 

Edward  d.  ScieXoth,  Jr. 

Neoterics,  Inc. 

C,  HODUXE  EONCIIOB 

This  module  initializes  two  TSS  clocks,  one  for  CPU 
time  and  the  other  for  CONNECT  time.  These  clocks  may 
be  read  at  a later  time  to  provide  the  elapsed  time 
plus  initial  values, 

D,  BATA  BEQDISEI3ENTS 

1.  I/O  Block  Diagram 
Not  Applicable 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Piles 
Not  Applicable 

c.  Input  Files 
Net  Applicable 

d.  On-line  Terminal  Entries 
Hot  Applicable 

3.  Output  Data  Sets 
a.  Output  Files 

Hot  Applicable 
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b.  Gn-line  Terminal  Displays 
Bot  Applicable 

c.  iormatted  Prlnt-onts 
Not  Applicable 

4.  Beference  Tables 
Hot  Applicable 

' E,  PBOCESSING  DEQtllEEHENTS 
1«  Top  Level  flowchart 
See  Pigtire  1 
2«  narrative 

In  the  STAET  entry,  the  initial  values  are 
assigned  to  the  total  clock  value  and  an  even  odd 
pair  of  clocks  are  started  even  (0)  vitb  task 
option  0DD(1)  with  real  option  and  two  counters 
are  set  with  these  values. 

In  the  READ  entry,  a flag  is  set  to  on  at  entry. 
The  clocks  are  read  and  the  initialized  totals  are 
updated.  The  clocks  are  stopped  and  restarted  to 
prevent  expiration,  the  values  are  provided  to 
caller  the  G-1  pair  of  clocks  started,  the 
indicator  turned  off  and  return  made  to  caller. 

In  the  STOP  entry,  the  two  counters  of  clock 
numbers  are  deducted  by  2 and  each  pair  of  active 
clocks  stopped. 

If  either  clock  should  expire,  the  expiration 
routing  post  full  values  to  total  and  starts  a 
new  clock  with  value  -*2  and  returns, 

E.  CODING  SPECIFICATIONS  , 

1,  Source  language 

Assembler 

. ■ Suggestions  and  Techniques 
Hot  Applicable 


2 
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TOPIC  G.5  - STATIC  EEPOET 


A.  HODUEE  NAME 

aaintenamce  statistics*  Report 
Program-ID  - EDBEENTH 
Koduls-IP  - PBPENTM 

B,  . ANALYST 

Eflward  J»  Scteioth,  Jr. 

James  A.  Wesley 
Heoterics,  Inc. 

C.  MODULE  PUNCTION 

This  program  opens  and  reads  the  STATIC  data  base 
<segnential  inpnt) ; analyzing,  accumulating  and 
formatting,  {for  printing)  the  maintenance  statistics* 
information  ^hich  is  currently  posted.  The  end  result 
is  a maintenance  statistics*  report.  It  has  the  added 
function  of  snapshot  dump  and  re- initializing  the 
seven  variable  element  fields  which  are  the  running 
totals  of  the  maintenance  statistics, 

D,  DATA  BEQUIBEMENTS 

1,  I/O  Block  Diagram 
See  Eigure  1 

2,  Input  Data  Sets 

a.  Parameter  cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

The  STATIC  data  base  {for  detailed  and 
complete  information  on  this  data  base  refer 
to  Section  III  of  the  Development 
Workbook)  . 

d.  On-line  Terminal  Entries 
Not  Applicable 
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3.  Output  Data  Sets 
a.  Output  Piles 

Kot  applicable 

b*  On-liue  feriniual  Displays 

Mot  Applicable 

c.  formatted  Print-outs 

The  maintenance  statistics  report  (for 
complete  detailed  information  on  this  listing 
refer  to  Section  III  of  the  Development 
Mcrfcbook) » 

h,  Reference  Tables 
Hot  applicable 
PROCESSING  ESQUIEEHENTS 
1.  Top  Level  Flowchart 
See  Figure  2 
2«  Narrative 

This  module  performs  the  following  logic  in  order 
to  produce  the  maintenance  statistics*  report: 

a.  Opens  the  STATIC  data  base  for  sequential 
input  (use  DBPl/I)  . 

b»  Bead  the  STATIC  file  sequentially,  record  by 
record,  and  while  reading  constructs  from 
the  current  information  on  the  STATIC  data 
base,  the  required  listing* 

c.  Outputs  the  print  file  required  to  produce 
the  maintenance  statistics*  report. 

d*.  Snapshots  the  ten  variable  element  fields  if 
they  are  full. 

e.  Close  All  Files:  Terminate, 

Note:  It  is  necessary  for  this  program  to 

accumulate  various  information  so  that  it 
can  output  the  summary  of  maintenance 
statistics. 
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CODING  SPECIEICAIIOHS 

1,  Source  language 

The  IDEPENTH  module  is  coded  in  the  IBH 
programming  language  PL/I,  The  DBPL/I  and  TSPL/I 
language  extensions  are  used  for  data  base  access 
and  terminal  1/0,  respectively. 

2,  Suggestions  and  Techniques 

Eefer  to  Section  III  of  the  Development  Workbook 
for  all  data  set  specifications  and  all  data  base 
executive  errors. 


SM 


Figure  1.  I/O  Block  diagram 
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TOPIC  G.6  - BITBIBVIX  STATISTICS  BIEBCTOB 

A.  . EODULB  HAHB- 

EetrieT/al  Statistics 
Prograni-ID  - RDBSTAT 
Hoaale-ID  - DBSTAT 

B.  ANALYST 

James  A.  Wesley 
Neoterics,  Inc, 

C.  NODDLE  FUNCTION 

This  module  is  the  heart  of  the  retrieval  statistics^ 
It  has  an  entry  point  for  each  retrieval  module 
included  in  the  statistics, 

D.  DATA  SEQUIEEHENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Not  Applicable 

d.  On-line  Terminal  Entries 
Hot  Applicable 

3,  Output  Data  Sets 

a.  Output  Files 

The  Static  data  base, 

4 

b.  On-line  Terminal  Displays 
Net  Applicable 
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c,  Eorma-tted  Prin±-outs 
Mot  Applicable 

d,  PuncKed  Card  Ou-tp'ut  Files 
Kot  Applicable 

4,  Refereuce  Tables 

*FI»PTAB*  is  used  to  convert  inverted  indices  to 
data  base  file  names. 

PE0CESSIH6  EEQUIBiaENTS 

i.  , Top  level  Flowchart 

See  Figure  2 

2»  Narrative 

The  INIT  entry  chechs  to  see  if  there  was  a crash 
during  the  last  session  by  the  existence  of  the 
ONES  record  and  then  write  one  if  there  wasn’t  one 
or  after  EEECHKPT  deletes  it.  INIT  initializes 
statistics  that  like  INIT  in  the  command  system 
setting  up  the  necessary  tables  or  pointers  for 
later  use. 

Each  command  entry,  one  each  for  EXPAND,  SEIECT, 
SEAECS  and  COEBECT,  pushes  its  information, 
command  type,  NASISID  OENEBID  and  fill,  into  the 
stack  and  then  checks  to  see  if  it  is  time  to 
update  the  statistics  by  checking  the  command 
count  and  entry  count  for  critical  level. 

The  DBSTATE  entry  call  on  termination  of  a 
session,  just  indicates  that  this  is  to  be  the  end 
and- provides  strategy  information  and  branches  to 
the  PPTSTAT  routine. 

The  DESTATD  entry  deletes  this  strategy  from  the 
statistics  if  it  is  there. 

The  PDTSTAT  routine  always  updates  the  CPU-  and 
connect  time  by  calling  the  ETIHEES  routines  for 
their  values.  It  also  always  pops  the  command 
stack  and  updates  each  command  count  and  the 
set-date  fox  the  specified  file.  The  stack  is  a 
FIFO  stack,  a one  dimensional  structured  array. 
If  this  is  a DBSTATE  entry,  then  the  strategy 
information  ’STEATNHE’,  ’STEATSTE,*  and  ’STEATIER* 
and  usage  information  ’lASTDATE’  are  complete 


PAGE  535 


updates.  Finally,  for  the  DBSTATF  entry  to  update 
the  storage  allocation  is  freed  and  the  ones 
record  deleted  from  STATIC, 

CODING  SPECIFICATIONS 

1»  Source  language 
Pl/I  and  DBPl/I 

2. _ Suggestions  and  Techniques 
Not  Applicable 
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PUSH 
COMMAND 
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IN  STACK 


EXPAND, 

SELECT, 

CORRECT, 

SEARCH 


UPDATE 

STRATLEN 


Entries  OR 

^COMMAND 

SlilMlT 


UPDATE 


CPU  AND 


CONN.  TIME 


ON  STATIC 


UPDATE 
STRAIN  ME 


c 

S' 

LOSE 

FATIC 

c/\ 

RD 

LL 

BCHKPT 

i 

C 

5 

IPEN 

iTATIC 

IN 

A^ 

AL 

ITIALIZE 

ID 

LOCATE 

7 

RETURN 


FINISH 

ENTRY 


INDICATE 
THIS  IS 
FINISH 


UPDATE 
SESSDATE  FOR 
EACH  FILE  IN 
COMMAND 
STACK 


UPDATE 
FOR  EACH 
COMMAND 
IN  STACK 


ARE  X 
MORE  IN 
STACK 


UPDATE 

STRATSTR 


UPDATE 
LAST  DATE 


CLOSE 

STATIC 


DELSTRAT 


IS  \ 
'^TRAT.  NAME 
Von  FILE  > 


RETURN 


Figure  2.  Top  level  flowchart 


TOPIC  H. 1 


EXPiaiN  EACILIT? 


A.  MODULE  NAME 

Program-ID  - HDBEXEL 
MODBLE-IE  - DBEXPL 

B.  . ANALYST 

John  A.  Lozan 
Neoterics#  Inc, 

C.  aOBDLE  ETJNCTION 

This  module  allows  the  user  to  display  the  explanation 
of  a message  or  term,  the  origin  of  a message  or  the 
responses  to  a prompt,  that  has  appeared  on  the  screen, 
or,  the  text  of  any  of  the  standard  prompting  messages 
on  the  message  file, 

B.  DATA  HEQDIBEHENTS 

1 , I/O  Block  Diagram 
See  Eigure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Not  Applicable 

d.  On-line  Terminal  Entries 

This  module  receives  its  input  in  the  form  of 
parameters  passed  with  the  EXPLAIN  or  PROMPT 
commands, 

3,  Output  Data  Sets 
a.  Output  Files 

Not  Applicable 
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b.  Cn-*lii5e  lerminal  Bisplays 

This  moitile  displays  the  requested 
information  for  the  user  on  the  terminal, 

c.  Format-ted  Print-Outs 
Bot  Applicable 

d.  Punched  Card  Output  Files 
wot  Applicable 

4.  Reference  Tables 
Sot  Applicable 
PHOGESSISG  HEQDIREHENTS 

1,  Top  level  Flowchart 
See  Figure  2 

2,  . Narrative 

a,  PEEXPII 

Upon  entry,  the  program  inixxaj.izes  me 
variables  that  control  execution  and  the 
displaying  of  data  to  the  user.  It  also  sets 
up  the  mechanism  by  which  paging  is  to  be 
accomplished. 

Next  the  program  prompts  for  the  OPTION  and 
KESSAGE  parameters  required-  for  the  EXPLAIN 
function.  It  verifies  that  the  option 
selected  is  valid,  and  if  so,  branches  to  the 
appropriate  routine. 

For  simple  explains,  i,e,,  message 
explanations,  the  OPTION  is  treated  as  an 
index,  verified,  and  the  line  number  set  to  a 
value  of  100,  If  the  OPTION  is  not  a valid 
index,  the  request  is  treated  as  a term 
explanation.  The  OPTION  is  then  treated  as  a 
qualified  term  and  used  to  construct  the 
message  key  which  is  used  to  locate  the 
term’s  explanation.  For  response 

explanations  the  live  number  is  set  to  a 
value  of  400, 

In  each  of  the  above  instances,  control  is 
passed  to  a routine  which  attempts  to  read  a 
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data  record.  If  saccessfal,  the  record  is 
Tsritten  to  the  screen  and  the  process 
repeated,  until  the  data  has  been  exhausted, 
or  the  screen  filled.  At  this  time,  the 
paging  controls  axe  set,  the  screen  is 
displayed  to  the  user  and  the  program  is 
terminated.  If  no  data  was  found,  the 
routine  branches  to  an  error  routine  which 
displays  a message  to  the  user  and  terminates 
the  program. 

If  the  original  request  was  for  a message 
origin,  the  OPIIOB  is  treated  as  an  index, 
and  if  valid,  the  appropriate  message  hey  is 
obtained,  displayed  to  the  user,  and  the 
program  is  terminated. 

b,  DBEXPL2 

At  this  entry  point,  the  program  initialises 
the  varriables  that  control  execution  and 
prompts  for  the  HESSA6E  parameter.  It  then 
prompts  for  the  INSERTS  parameter  list. 

Cnee  complete,  the  program  attempts  to 
display  the  message  indicated  with  the 
specified  inserts. 

c.  DBEXPIP 


At  this  entry  point  the  program 
re-inltialises  the  variables  that  control 
execution  and  the  displaying  of  data  to  the 
nser.  If  the  paging  status  data  indicates 
that  more  data  remains,  the  program  uses  this 
data  to  restore  the  proper  program  status  and 
then  branches  to  the  routine  which  posts  data 
to  the  screen.  If  no  data  remains  to  be 
displayed,  the  program  simply  terminates, 

CODING  SPECIPICATIONS 

1, . Source  language 

The  module  is  written  using  the  TSS  360  PL/I 
language . 

2,  Suggestions  and  Techniques. 

Not  Applicable. 


DBALIB 


LISRLIB 


SYS OUT  y 


Figure  1.  l/o  Block  Diagram 
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TOPIC  H, 2 - STPATEOY  INTEPiaCI 


A.  HODUIE  SAME 

Praqram-ID  - EDBSTPT 
Hoduls-in  - BBSTPI 

B.  AHAIYST 

John  i.  I02an 
Neo-terics,  Tnc. 

C.  KODULB  FUNCTIOH 

Ihis  module  serves  as  an  interface  between  the  strateqy 
data  set  service  routines  and  the  rest  of  the  NASIS 
system.  In  addition,  it  is  the  module  which  performs 
the  functions  specified  hy  the  FOPHAT?  and  STRATEGY 
commands,  i,e,,  the  listinq  of  format  and  strategy 
names,  the  listing  of  strategies  and  the  deletion  of 
strategies, 

D.  DAIA  HE0UIBE8EBTS 

1,  I/O  Bloch  riaqram 
^ee  Fiaure  1 

2,  Input  Data  Sets 

a,  Parameter  Cards 
Not  Anplicable 

b.  Punched  Card  Input  Files 
Bet  Applicable 

C,  Input  Files 

Bot  Apolicable 

i,  Cn-line  Terminal  Entries 

Phen  serving  as  the  processor  for  the  FOPBAT? 
and  STRSTEGY  commands,  the  program  reads  in 
the  command  and  parameters  specified  by  the 
user  to  invohe  those  commands, 

3,  Output  Data  Sets 
a,  Cutcut  Files 
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Not  Applicable 

b.  On-line  Terminal  Displays 

When  serving  as  the  processor  for  the  FOEHAT? 
and  STBATEGT  commands,  the  program  produces 
fhe  follcwing  formatted  screen  images, 

1,  Format  names  display 

2,  Strategy  names  display 

3,  Strategy  display 

c.  Formatted  Print  Outs 
Hot  Applicable 

d.  Punched  Card  Output  Files 
Hot  Applicable 

4.  Reference  Tables 

DSEETAB-is  used  to  obtain  the  HASIS-id  and  to  test 
the  task  status  as  represented  by  the  various  bit 
snitches. 

FXDTAE  -is  used  to  reference  the  formats  currently 
defined  for  this  user, 

PROCESSING  EEQUIREMENTS 

1,  Top  level  Flcwchart 
See  Figure  2 

2,  Narrative 

a,  6STRAT  and  GFOBH 

At  these  entry  points  the  program  initializes 
the  parameter  lists  necessary  to  obtain  a 
line  from  the  strategy  data  set,  and  calls 
TSGETBG  to  do  it.  If  an  error  occurs,  and  it 
is  the  first  error  for  that  region,  a 
diagnostic  message  uill  be  written  to  the 
user.  Otherwise,  the  program  simply  returns 
to  the  caller, 

b,  PSTBAT  and  PFOBK 


At  these  entry 


points  the  paragram 
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initializes  the  parameter  lists  necessary  to 
write  a line  to  the  strategy  data  set, 
including  the  generation  of  the  strategy  or 
format  name.  It  then  calls  TSPOTBG  to 
perform  the  write.  If  PSTSAT  is  called  and 
the  TESTHODE,  EEBDN  or  PESTACT  flags  are  set, 
the  program  immediately  returns  to  the 
caller.  If  an  error  occurs  while  writing  out 
the  record,  a diagnostic  message  is  written 
to  the  user  and  the  TESTMODE  switch  is  turned 
cn.  The  program  then  returns  to  the 
caller. 

C.  CSTEAT  and  CEOPH 

at  these  entry  points  the  program  initializes 
the  parameter  lists  necessary  to  change  the 
name  of  a region.  It  then  calls  TSCH6E6  to 
accomplish  the  change.  If  any  errors  are 
encountered,  a diagnostic  message  is  written 
to  the  user.  The  program  then  returns  to  the 
caller. 

d.  ESTEAT  and  DEOBH 

At  these  entry  points  the  program  initializes 
the  parameter  lists  necessary  to  delete  a 
region  of  tie  strategy  data  set.  It  then 
calls  TSDE1B6  to  perform  the  deletion.  If 
any  errors  are  detected,  a diagnostic  message 
is  written  to  the  user.  The  program  then 
returns  to  the  caller. 

e.  DBSTBT1 

At  this  entry  point  the  program  initializes 
itself  to  process  the  strategy  command.  It 
reads  in  the  OPTIOB  and  STBATEGY  parameters. 
The  program  then  branches  to  the  routine  used 
to  process  the  type  of  request  specified  by 
the  OPTION  parameter.  If  that  parameter  is 
not  Trail 6 , the  program  writes  a diagnostic 
message  and  terminates  immediately. 

If  the  user  requested  a strategy  deletion, 
the  program  calls  TSDBIHG  to  delete  the 
strategy  specified.  If  an  error  occurs,  a 
diagnostic  message  is  written  to  the  user. 
The  program  then  chechs  for  any  additional 
names,  and  processes  each  in  the  same  way. 
When  all  processing  has  been  completed  the 
program  terminates. 
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If  "the  user  reguested  a listing  of  the 
strategy  names,  the  program  initializes  the 
screen  and  paging  control  data*  It  then 
repetitively  calls  ISGETSN  to  retrieve  the 
names  cf  the  strategies.  As  each  name  is 
obtaine0,  it  is  added  to  the  output  line  and 
the  line  is  written  to  the  screen.  When  the 
screen  is  filled  or  when  the  strategies  names 
are  exhausted,  the  screen  is  displayed  to  the 
user,  the  paging  status  data  is  posted  and 
the  program  is  terminated. 

If  the  user  reguested  a listing  of  a 
particular  strategy,  the  program  initializes 
the  screen  and  paging  control  data.  The 
first  strategy  name  specified  is  selected, 
and  TSGETIG  is  repetitively  called  to  obtain 
the  lines  comprising  the  strategy.  Each  line 
is  posted  to  the  screen.  When  the  screen  is 
tilled  or  when  the  last  line  has  been 
written,  the  screen  is  displayed  to  the  user, 
the  paging  staters  data  is  posted  and  the 
program  is  terminated.  The  paging  status 
data  must  indicate  when  a strategy  has  been 
completely  listed,  so  that  the  next  name  from 
'the  list  can  be  used, 

f.  DBSTET2 

At  this  entry  point  the  program  initializes 
itself  to  display  the  names  of  the  formats 
available  to  the  user.  It  initializes  the 
screen  and  the  paging  status  data.  The 
program  then  extracts  the  identifiers  for  all 
of  the  formats  currently  specified  in  the 
format  tables.  It  then  calls  TSGETFS  to 
retrieve  the  name  of  a stored  format.  It 
places  the  names  of  the  formats  on  a line  and 
writes  the  line  out  to  the  screen.  The  names 
are  processed  alphabetically,  and  as  each 
stored  format  name  is  processed,  a new  one  is 
read  in.  Stored  formats  that  are  • also 
present  in  the  format  tables  are  only  shown 
once.  When  the  screen  is  filled,  or  when  the 
list  of  names  is  exhausted,  the  screen  is 
displayed  to  the  user,  the  paging  status  data 
is  posted  and  the  program  is  terminated. 

g,  BBSTETP 

At  this  entry  point  the  program 
re- initializes  itself  to  the  status  , saved 
before  the  last  < termination.  If  more  data 
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remains  to  te  displayed,  the  program  branches 
to  the  proper  routine  to  produce  the  next 
display  screen.  If  no  more  data  remains,  a 
diagnostic  message  is  written  to  the  user  and 
the  program  is  terminated. 

E.  , CODING  SPECIFICATIOHS 

1,  Source  Language 

The  module  is  written  using  the  ISS  360  *P1/I 
language. 

2.  Suggestions  and  Technigues 
Not  Applicable 
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Figure  2B.  Tot>  T,evp.1  ■p'lnr.Tpliar-t- 
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Figure  2C.  Top  Level  Flowchart 
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TOPIC  H.3  - STRATEGY  ASSEHBIEE  ROUTINES 

A.  fiODDLE  NAME 

Program-ID  - BTSSTBT 
Moaule-ID  - TSSTST 

B,  ANALYST 

John  A*  Lozan 
Neoterics,  Inc, 

C.  MODULE  EUHCTION 

These  Totitines  act  as  the  assembler  service  routines 
for  the  strategy  library.  They  permit  the  retrieval, 
modification  and  storing  of  the  saved  strategies  and 
formats, 

D,  DATA  REQUIREMENTS 

1.  I/O  Elock  Diagram 
See  Pigure  1 

2.  Input  Data  Sets 

a,  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Piles 
Not  Applicable 

C.  Input  Piles 

Strategy  data  set  - is  ■ used  for  input  for 
both  stored  strategies  and  stored  formats, 

IBAlIE-member  FORMATS  is  used  for  input  for 
stored  formats  only. 

d.  On-line  Terminal  Entries 

Net  Applicable 

3.  Output  Data  Sets 
a.  Output  Files 

Strategy  Data  Set-is  used  for  output  for  both 
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stored  strategies  and  stored  formats. 

b.  On-line  terminal  Displays 
Not  Applicable 

c.  Ecimatted  Print  Outs 
Not  Applicable 

d«  PuncHed  Card  Output  Files 
Not  Applicable 

4,  Reference  Tables 

OSEETAB-is  used  to  obtain  the  NASIS-ID. 

PBOCESSING  EEQUIRIKEHTS 

1,  Top  Level  Flowchart 

See  Figure  2 

2.  Narrative 

T 

a.  TSDEIBG 

At  this  entry  point  the  program  initializes 
itself  to  delete  a strategy  or  format  region. 
It  opens  the  strategy  data  set,  if  necessary, 
and  extracts  the  region  name  passed  by  the 
caller.  The  program  then  proceeds  to  delete 
the  region,  one  line  at  a time.  If  any 
errors  are  encountered,  the  region  name  is 
set  to  null.  The  program  then  returns  to  the 
caller. 

b.  TSGETEG 

At  this  entry  point  the  program  initializes 
itself  to  get  a line  from  a strategy  or 
format  region.  It  opens  the  strategy  data 
set  and  member  FOBHATS  of  DBAIIB{0)  if 
necessary.  It  extracts  the  parameter  passed 
'by  the  user,  and  if  a null  line  number  is 
passed,  sets  up  to  read  the  first  line  of  the 
region.  If  the  high  order  bit  of  the  line 
number  is  off,  it  sets  up  to  read  the  line 
following  that  indicated  by  the  line  number. 
Otherwise , it  positions  the  pile  to  the  line 
number  passed. 
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The  program  then  attempts  to  read  the  line 
requested.  If  successful,  it  posts  the  line 
number,  posts  the  data  {^ith  trailing  blanks 
removed)  and  returns  to  the  caller. 

If  a^i  error  occurs,  the  program  sets  the 
region  name  to  null  before  returning, 
likewise , if  an  end-of -region  occurs,  the 
line  number  is  set  to  null  before  returning. 
If  the  region  cannot  be  located  in  the 
strategy  data  set,  the  program  checks  the 
region  name,  and  if  it  is  a format  request, 
tries  to  locate  the  region  in  member  POEHATS 
of  DBM1IB{0)  and  then  processes  the  request 
as  indicated  above. 

C.  TSPUTEG 

At  this  entry  point  the  program  initializes 
itself  to  pnt  a line  to  a strategy  or  format 
region.  It  opens  the  strategy  data  set,  if 
necessary,  and  extracts  the  region,  live 
number  and  data  parameters  passed  by  the 
caller.  If  the  line  number  is  null,  it  sets 
up  to  add  the  line  at  the  end  of  the  region. 
In  any  case,  it  positions  the  file  to  the 
proper  region  and  live  within  the  region. 
The  program  then  attempts  to  write  out  the 
new  line  from  the  data  passed  by  the  caller. 
If  successful  the  program  simply  returns  to 
the  caller.  If  an  error  occurs,  the  program 
sets  the  region  name  to  null  before 
returning. 

d.  TSCHGBG 

At  this  entry  point  the  program  initializes 
itself  to  change  the  name  of  a strategy  or 
format  region.  It  opens  the  strategy  data 
set  if  necessary,  and  extracts  the  old  and 
new  region  names  passed  by  the  caller. 

The  program  firsts  attempts  to  delete  any 
existing  region  with  the  new  region  name.  If 
an  error  occurs,  • other  than  region  unknown, 
the  program  terminates  and  sets  the  old 
region,  reads  a line,  positions  itself  to  the 
new  region  and  writes  out  the  live.  This 
process  is  repeated  until  all  of  the  data 
lines  have  been  copied.  If  any  errors  occur, 
the  new  region  is  deleted,  the  old  region 
name  is  set  to  null  and  the  program  returns 
to  the  caller.  If  no  errors  have  occurred. 
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the  program  deletes  the  old  region  and 
returns  to  the  caller, 

e,  ISGETSU 

At  this  entry  point/  the  programs  initializes 
itself  to  get  a strategy  region  name.  It 
opens  the  strategy  data  set,  if  necessary, 
and  extracts  the  strategy  name  passed  by  the 
caller.  If  the  name  is  null,  the  program 
sets  up  to  get  the  first  strategy  name. 
Otherwise,  it  sets  up  to  get  the  strategy 
name  following  that  passed  by  the  caller. 

The  program  then  attempts  to  read  a line  from 
the  strategy  data  set.  If  successful,  it 
extracts  the  region  name  and  passes  that  bach 
to  the  caller.  If  an  error  occurs,  or  if  an 
end-of-file  is  sensed,  the  region  name  is  set 
to  null  and  the  program  returns  to  the 
caller. 

f.  ISGE-TEN 

fit  this  entry  point,  the  program  initializes 
itself  to  get  a format  region  name.,  It  opens 
the  strategy  data  set  and  member  FOBHATS  of 
DBAIIB  (0) , if  necessary,  and  extracts  the 
region  name  passed  by  the  caller.  If  the 
region  name  is  null,  the  program  sets  up  to 
get  the  first  format  name.  Otherwise,  it 
sets  up  to  get  the  format  name  following  that 
passed  by  the  caller, 

The  program  then  attempts  to  read  a line  from 
both  data  sets.  If  an  error  occurs,  or  if 
both  files  indicate  end-of-file,  the  region 
name  is  set  to  null  and  the  program  returns 
to  the  caller.  Otherwise,  the  program 
compares  the  region  names  of  the  two  lines. 
It  posts  the  name,  lowest  in  value,  in  the 
region  name  and  returns  to  the  caller, 

CODING  SPECIFICATION 

1.  Source  Language 

The  module  is  written  using  the  TSS  360  Assembler 

language 

2.  Suggestions  and  techniques 

Any  output  operation  to  the  strategy  data  set 
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results  in  the  temporary  closing  of- the  data  set, 
to  ensure  data  set  integrity  in  the  event  of  a 
system  crash. 
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Figure  1.  l/o  Block  Diagram 
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TOPIC  H.4  - DSIK  ?EBE  TABLE 

A.  MODULE  NAME 

Program-ID  - RDBUSEE 
flodula-ID  - DBDSE5 

B.  ANALYST 

John  A.  Lozan 
Neoterics,  Inc. 

C.  HODDLE  PDNCTION 

This  routine  uses  the  currently  defined  verb  table  to 
locate  any  user  defined  commands  for  that  table.  If 
any  have  teen  defined,  they  are  appended  to  the  list 
already  .existing  in  the  table. 

D.  DATA  REQDIHEKENTS 

1.  I/O  Block  Diagram 
Not  Applicable 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

C.  Input  Files 

Not  Applicable 

d.  On-line  Terminal  Entries 
Not  A-pplicable 

3.  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  Gn-line  Terminal  Displays 
Not  Applicable 
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c.  Eormattcd  Print  Outs. 

Mot  Applicable 

d.  Punched  Card  Outpul:.  Files 


4,  Reference  !Eables 
VEEET2E 

"E.  PEOCESSIMG  EEQUIHEHEHTS 

1 , lop  Le-vel  Flowchart 
See  Figure  1 

2,  Narrative 

Upon  entry,  the  program  tests  for  the  presence  of 
a VEBBTAE,  If  none  is  found,  it  exits 
immediately.  Otherwise,  the  program  extracts  the 
default  symbcl  from  the  table  and  gets  the  default 
value  for  that  symbol. 

The  program  then  begins  analyzing  the  data,  until 
none  remains,  at  which  time  it  returns  to  the 
caller.  The  data  is  expected  in  command-name  and 
entry  point  pairs.  Each  pair  is  extracted  from 
the  data,  analyzed  for  valid  construction  and  then 
posted  to  the  next  available  slot  in  the  table. 

If  there  are  any  syntax  errors,  invalid  names,  or 
if  the  table  is  filled,  the  program  will  return  to 
the  caller,  bypassing  the  remaining  entries. 

F.  CODING  SPECIFICATICNS 

1,  Source  language 

The  module  is  written  using  the  TSS  360  PX/I 
language, 

2,  . Suggestions  and  Techniques 

Not  Applicable 
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TOPIC  H.5  - USEB  PEOTIIE  EOPTIHB 

A.  HODDIE  EAHi 

Program-ID  - EDBPBG 
Hodule-ID  - DBPBO 

B.  ANALYST 

John  A*  L02an 
Neoterics,  Inc. 

C.  HODOLE  PTINCTION 

This  modnle  perforins  the  processing  necessary  for  the 
implementation  of  the  PEOEILE,  SYKONYH,  DEPAOIT, 
SYNOKYH  and  DEFAULT  commands. 

D.  DATA  BEQUIEEMENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Kot  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Sot  Applicable 

d.  On-Line  Terminal  Entries 

The  program  prompts  the  user  for  the 

parameters  required  by  the  various 
commands. 

Output  Data  Sets 


a. 


b. 


3 


Output  Files 

Set  Applicable 

On-line  Terminal  Displays 
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Ihe  display  of  the  user’s  defaults  and 
synonyms  produce  formatted  terminal 

displays. 

c.  Formatted  Print  Outs 
Not  applicable 

d.  Punched  Card  Output  Files 
Kot  Applicable 

4.  Eeference  Tables 

USEPTAB-the  program  extracts  the  user’s  HASIS-'id 

from  the  user  data  table. 

PHOCESSING  BEQniREKEHTS 

1.  Top  level  Flowchart 

See  Figure  2 

2.  Narrative 

a.  TBPEOF 

at  this  entry  point  the  program  simply  calls 
TSPBOF  to  write  out  . a copy  of  the  user’s 
current  profile.  If  any  errors  are  detected, 
an  appropriate  diagnostic  message  is  written 
to  the  user  the  program  then  terminates, 

b.  DBDEF 

at  this  entry  point  the  program  initializes 
itself  to  process  defaults.  It  repetitively 
prompts  for  data  and  calls  TSPDEF  to  process 
the  request.  If  any  errors  are  encountered, 
an  appropriate  diagnostic  message  is  written- 
to  the  user.  The  program  then  terminates, 

c.  DBSYN 

at  this  entry  point  the  program  initializes 
itself  to  process  synonyms.  It  repetitively 
prompts  for  data  and  calls  TSPSYN  to  process 
the  request.  If  any  errors  are  detected,  an 
appropriate  diagnostic  message  is  written  to 
, the  user.  The  program  then  terminates. 

d.  DBDEFS 
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At.  this  entry  point  the  program  initializes 
itself  to  display  the  data  values 
corresponding  to  a set  of  default  symbols, 
fhe  program  also  initializes  the  screen  and 
paging  control  data.  The  program  then 
attempts  to  read  in  the  list  of  symbols.  If 
no  data  was  entered,  the  program  sets  up  to 
display  all  of  the  default  values.  Otherwise 
it  saves  the  list  of  symbols  entered. 

The  program  then  repetitively  calls  TSGDE? 
for  each  entry  in  the  list,  to  obtain  its 
default  value.  The  values  are  formatted  and 
posted  to  the  screen.  When  the  screen  is 
filled,  or  when  the  list  of  names  is 
exhausted,  the  program  displays  the  screen  to 
the  user,  posts  the  paging  status  data  and 
terminates. 

6,  IBSYHS 

At  this  entry  point  the  program  initializes 
itself  to  display  the  time  values  for  a set 
of  synonym  terms.  The  program  also 
initializes  the  screen  and  the  paging  control 
data.  The  program  then  attempts  to  read  in 
the  list  of  symbols. 

If  no  data  was  entered,  the  program  sets  up 
to  display  all  of  the  synonym  values. 
Otherwise,  it  saves  the  list  of  symbols 
entered. 

The  program  then  repetitively  calls  TSGSYE 
for  each  entry  in  the  list,  to  obtain  its 
time  value.  The  values  are  formatted  and 
posted  to  the  screen.  When  the  screen  is 
filled,  or  when  the  list  of  names  is 
exhausted,  the  program  displays  the  screen  to 
the  user,  posts  the  paging  status  data  and 
terminates. 

f.  DEPBOPG 

At  this  entry  point  the  program 
re-initializes  itself  using  the  paging  status 
data.  If  data  remains,  the  program  branches 
to  the  proper  routine  to  produce  the  next 
screen  image.  Otherwise,  the  program  writes 
a diagnostic  message  and  terminates. 


E 


CODIHG  SPECIPICATIOMS 
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1.  . Source  language 

The  program  is  written  using  the  TSS  360 
language, 

2,  Suggestions  and  Techniques 
Not  Applicable 


PL/I 


Figure  2B.  Top  Level  Flowchart  - DBDEFS,  DBSYNS 


Y) 
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TOPIC  H.6  - DSEH  PROPIIE  ASSEHBLEB  BOUTIUES 

A.  MODULE  NAME 

Program -ID  - STSPBO 
Hodule-ID  - ISPBO 

B.  ANALYST 

John  A.  Lo-zan 
Neoterics,  Inc, 

C.  MODULE  EDNCTION 

These  routines  act  as  the  assembler  service  routines 
for  the  user’s  profile.  They  permit  the  retrieval, 
modification  and  storing  of  all  synonym  and  default 
values, 

D.  DATA  BEQDIEEMENTS 

1,  I/O  Block  Diagram 
See  Figure  1 

2,  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 

PBOFILE  LIBBAEY  or  DBALIB (0) (NASISPRO)  or 
IISRLIB{0) (NASISPBO)  is  used  to  initially 
obtain  a profile  for  the  user, 

d.  On-line  Terminal  Entries 
Not  Applicable 

3,  Output  Data  Sets 
a.  Output  Files 

PROFILE  LIBBABY  - the  user’s  profile  will  be 
written  out  as  a member  of  this  library  with 
, the  name  of  his  NASIS-id, 
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b.  Ou-liue  Terninal  Displays 
Bot  Applicable 

c,  lormattefl  Print  Outs 
Hot  Applicable 

a.  Puncfied  Card  Output  Files 
Hot  Applicable 
e.  Eeturn  Code 

A return  code  will  be  posted  with  a value 
whose  meaning  is  dependent  upon  the  entry 
point  called* 

4.  Eeference  Tables 

USEETAB-the  program  extracts  the  user’s  NASIS-id 
from  the  user  data  table, 

PEOCESSIBG  RBQTJIREHEHTS 

1.  Top  level  Flowchart 
See  Figure  2 

2,  Narrative 

a.  TSPBOF 

At  this  entry  point  the  program  initializes 
itself  to  write  out  the  current  user's 
profile.  It  first  allocates  a new  list  and 
moves  over  all  of  the  synonym  entries  not 
marked  for  deletion.  It  next  moves  over  all 
of  the  default  entries  and  re-orders  the 
default  data  values.  The  program  then 
attempts  to  locate  an  old  profile  for  this 
user  in  the  profile  library.  If  one  is 
found,  it  is  deleted.  The  program  then 
writes  out  the  new  profile  and  gives  it  the 
name  of  the  user’s  HASIS-id,  If  any  errors 
are  encountered  the  error  code  is  posted. 
The  program  then  returns  to  the  caller, 

b.  TSGSYK 

At  this  entry  point  the  program  initializes 
itself  to  retrieve  a synonym  value.  It  first 
searches  the  synonym  entries  until  it  locates 
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the  logical  location  for  the  symbol 
specified.  If  the  entry  is  present  and  has 
net  been  deleted,  or  if  the  entry  located  is 
fhe  symbol  vhose  abbreviation  was  specified, 
the  synonym  value  is  extracted  and  passed 
back  to  the  caller.  If  the  entry  located 
did  not  correspond  to  the  symbol  specified,  a 
null  value  is  returned  to  the  caller. 

C.  ISGDEF 

At  this  entry  point  the  program  initializes 
itself  to  retrieve  a default  value.  It  first 
searches  the  default  entries  until  it  locates 
the  logical  location  for  the  symbol 
specified.  If  the  entry  is  present,  the  data 
value  offset  is  located  and  the  data  value  is 
moved  into  the  caller’s  area.  The  program 
then  returns  to  the  caller. 

d,  I-SPSYH 

At  this  entry  point  the  program  initializes 
itself  to  post  a synonym  value.  It  first 
checks  to  see  if  this  is  a delete  request. 
If  not,  the  program  builds  the  new  entry*  It 
then  searches  the  synonym  entries  until  it 
locates  the  logical  location  for  the  symbol 
specified.  If  the  symbol  is  to  be  deleted 
and  it  is  not  present,  the  program  returns 
immediately.  Otherwise,  it  performs  the 
deletion  by  copying  the  entries  prior  to  the 
deleted  entry  and  those  following  the  deleted 
entry,  to  a new  profile  similarly. 
Similarly,  adds  are  processed  by  inserting 
the  added  entry  between  the  two  list 
segments,  Hodif icatlons,  if  allowed,  are 
performed  in  place.  If  a new  profile  was 
created,  the  old  list  is  deleted.  If  the 
request  was  not  for  a deletion,  the  program 
computes  the  minimum  abbreviation  length.  If 
it  was  a deletion,  all  synonyms  for  the  entry 
deleted  are  flagged  as  deleted.  The  program 
then  returns  to  the  caller, 

e.  TSPDEE 

At  this  entry  point  the  program  initializes 
itself  to  post  a default  'value.  It  first 
checks  to  see  if  this  is  a delete  request. 
If  not,  the  program  builds  the  new  entry.  It 
then  searches  the  default  entries  until  it 
locates  the  logical  location  for  the  symbol 
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specified*  If  the  symbol  is  ‘ to  be  deleted 
and  it  is  not  present,  the  program  returns 
iransediately . Otherwise,  it  performs  the 
deletion  by  copying  the  entries  preceding  the 
one  to  be  deleted  and  those  following  it  to  a 
new  profile*  Similarly,  adds  are  processed, 
by  inserting  the  added  entry  between  the  two 
list  segments  and  appending  the  data  value  at 
the  end  of  the  profile,  Hodif ications  are 

performed  in  place,  if  possible,  if  not,  the 
data  value  is  simply  added  to  the  end  of  the 
profile.  The  program  then  returns  to  the 
caller, 

CODING  SPECIFICATIONS 

1,  Source  language 

The  module  is  written  using  the  TSS  360  Assembler 
language, 

2,  Suggestions  and  Techniques 

The  entry  searching  routine  should  be  coded  as  a 
binary  search  and  the  list  moving  routine  should 
he  coded  as  efficiently  as  possible. 
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Figure  1.  I/O  Block  Diagram 
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Figure  2A.  Top  Level  Flowchart  - TSPROF,  TSGSYN,  TSGDEF 


Figure  ■'2B?  Top  Level  Flowchart  - TSPSYN,  TSPDEF 
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OrOPIC  H.7  - TES^EIHG  FACIIITY 

A.  MODULE  NAME 

Program-ID  - BTSTEST 
Hodule-ID  - TSTEST 

B.  AHALYST 

John  A,  1-ozan 
Neoterics,  Inc. 

C.  MODULE  FUNCTION 

This  raodnle  provides  a set  of  debugging  services  to  be 
used  in  the  testing  and  debugging  of  the  TSS 
functions. 

D.  DATA  EEQUIEEBENTS 

1.  I/O  Block  Diagram 
See  Figure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Tiles 
Not  Applicable 

d.  On-Line  Terminal  Entries 

The  program  can  execute  any  of  the  TSS  inpuf 
functions. 

3.  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  ’On-Line  Terminal  Displays 

The  program  can  execute  any  of  the  TSS  output 
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functions, 

c,  Eorin-atted  Prin±  Outs 
Kot  Applicable 

d.  Punched  Card  Output  Piles 
Hot  Applicable 

4,  Seference  Tables 

The  program  optionally  allocates  and  initializes 
USEBTAB. 

PBOCESSIHG  BEQUIEEHENTS 

1.  Top  Level  Plovichart 
See  Figure  2 

2,  narrative 

Upon  entry,  the  program  initializes  the  variables 
that  it  uses,  including  the  TC  block.  The  program 
then  calls  TSTESTE  to  prompt  the  user  for  a 
debugging  reguest.  It  verifies  that  the  users 
input  is  one  of  the  valid  requests  and  that  the 
associated  parameters  are  also  valid.  If  not, 
the  program  calls  TSTESTH  to  issue  a diagnostic 
message  and  then  re-prompts  the  user. 

If  the  reguest  vas  EHP,  the  program  simply 
terminates.  If  the  reguest  -was  TSS  the  program 
calls  TSTESTP  to  allow  the  user  to  enter  TSS 
command  mode.  If  the  request  was  PAD,  the  program 
moves  into  the  output  buffer  the  number  of 
characters  of  prestored  text  specified  by  the 
user’s  parameter. 

If  the  request  was  DO,  the  program  compares  the 
parameter  to  the  list  of  valid  TS2  functions  and 
abbreviations  and  calls  the  one  specified. 

If  the  request  was  SET,  the  program  passes  the 
parameters  passed  into  A=B  pairs.  The  A 
component  is  compared  to  the  list  of  valid  data 
fields  and  abbreviations  and  the  appropriate  data 
field  is  assigned  the  value  indicated  by  the  B 
component. 

If  the  request  was  EXP,  the  program  displays  a 
list  of  the  abbreviations  recognized  and  their 
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corresponding  data  field  or  function  names. 

If  the  request  was  BB,  the  program  passes  the 
parameters  and  displays  the  addresses  of  those 
data  fields  whose  names  or  abbreviations  were 
entered. 

If  the  request  was  BIS,  the  program  passes  the 
parameters  and  displays  the  current  values  of  the 
data  fields  whose  names  or  abbreviations  were 
entered. 

If  any  of  the  requests  are  improperly  specified  or 
reference  unknown  data  fields,  a diagnostic 
message  is  issued  to  the  user.  Following  this,  or 
at  the  completion  of  the  request,  the  user  is 
prompted  for  his  next  request. 

CODING  SPECIFICBTICNS 

1,  Source  Language 

The  module  is  written  using  the  TSS  360  PL/I 
language. 

2,  Suggestions  and  Techniques 

Proper  use  of  data  field  redefinition  will 

simplify  the  processing  of  some  of  the  requests, 

A function  will  have  to  be  written  to  return  the 
string  dope  vectors  as  processable  data'  in 
certain  instances. 


T7*f  o-t  fr<a  *} 
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!nOPIC  B,8  - TESTING  TACIIITY  3/0  INTEEPACE 

A,  HOCULE  MAHI 

Program-ID  - ETSTESTX 
Hodule-IC  - TSTESTX 

B,  ANAIYST 

John  A.  Lozan 
Neoterics,  Inc« 

C,  MOPOLB  PUNCTION 

This  program  serves  as  the  inpnt/oatput  interface 
hetueen  the  terminal  support  test  driver  and  the 
terminal. 

P.  PATA  BEQOIEEMENTS 

1.  I/O  Bloch  Piagram 
See  Pigure  1 

2.  Input  Data  Sets 

a.  Parameter  Cards 
Not  Applicable 

b.  Punched  Card  Input  Files 
Not  Applicable 

c.  Input  Files 
Not  Applicable 

d.  On-Line  Terminal  Entries 

At  the  read  entry  point  the  program  accepts 
input  from  the  terminal. 

3.  Output  Data  Sets 

a.  Output  Files 
Not  Applicable 

b.  On-Line  terminal  displays 

At  the  write  entry  point  the  program  displays 
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the  information  passed  by  the  caller, 
c.  formatted  Print  Outs 
Sot  Applicable 

a.  Punched  Card  Output  Piles 
Hot  Applicable 
4,  Heference  Tables 
Net  Applicable 

E,  PBOCESSING  BPQUIEEHIHTS 
1.  Top  Level  flowchart 
See  Figure 
2’.  Narrative 

At  each  entry  point  the  program  initializes  itself 
to  perform  these  appropriate  functions.  . The 
program  then  completes  the  entry  linkage  by 
calling  the  PL/I  linkage  module  IHESADA. 

If  a read  was  requested,  the  program  issues  a 
GTHAE  macro  to  read  from  the  terminal.  Any  data 
that  is  entered  is  moved  to  the  caller *s  parameter 
and  its  dope  vector  is  adjusted  to  reflect  the 
length  of  the  data. 

If  a write  was  requested,  the  data  contained  in 
the  caller’s  parameter  is  moved  to  the  output 
area  and  written  to  the  user  by  means  of  a 6ATHB 
macro. 

If  a pause  was  requested,  the  program  issues  a 
CLIC  macro  to  place  the  task  back  into  TSS 
command  mode. 

When  the  requested  function  has  been  completed  and 
the  parameter  posted,  if  necessary,  the  program 
returns  to  the  caller. 

P.  COSIHG  SPECIFICATIONS 

1,  Source  Language 

The  module  is  written  using  the  TSS  360  Assembler 
language. 


Suggestions  and  !Technigues 
Not  Applicable 


